Skip to content

feat: add UUID string converter (#1017) - #1088

Open
zhanghuang090 wants to merge 1 commit into
apache:mainfrom
zhanghuang090:codex/add-uuid-string-converter
Open

feat: add UUID string converter (#1017)#1088
zhanghuang090 wants to merge 1 commit into
apache:mainfrom
zhanghuang090:codex/add-uuid-string-converter

Conversation

@zhanghuang090

Copy link
Copy Markdown

Purpose of the pull request

Related: #1017

Fields declared as java.util.UUID currently have no built-in converter. This adds UUID ↔ STRING conversion so identifiers can be imported and exported without a custom converter.

Proposal: #1017 (comment)

What's changed?

  • Add UuidStringConverter, using UUID.fromString() for non-empty input and UUID.toString() for canonical lowercase output. Empty strings are treated as missing values, consistently with blank cells.
  • Register STRING reads, default writes, and explicit STRING writes in DefaultConverterLoader.
  • Add 18 JUnit 5 cases covering lookup paths, uppercase and boundary UUIDs, malformed input, and XLSX/XLS/CSV round trips, including null fields and empty strings. Malformed non-empty cells retain the framework's ExcelDataConvertException with the parsing error as the cause.
  • Keep the implementation compatible with Java 8 and add no dependencies.

Validation

  • Targeted UUID and existing loader tests: 22 passed (JDK 25.0.4.1, Maven 3.9.8).
  • Full module regression: 60 common tests passed; 934 spreadsheet tests had 0 assertion failures and 1 existing ClassUtilsFieldOverrideTest cleanup error (DirectoryNotEmptyException while deleting a JUnit temporary directory on Windows). A focused rerun of that class plus UUID and loader tests passed all 27 cases without code changes.
  • mvn -B -ntp -pl fesod-sheet -am -Dmaven.test.skip=false -Dtest=ClassUtilsFieldOverrideTest,UuidConverterTest,DefaultConverterLoaderTest -Dsurefire.failIfNoSpecifiedTests=false package spotless:check passed.
  • New converter compiles with javac --release 8 against the built project classes.
  • git diff --cached --check passed.

Checklist

  • I have read the Contributor Guide.
  • I have written the necessary doc or comment.
  • I have added the necessary unit tests and all cases have passed.

* Converts UUID values to canonical lowercase strings and reads strings using {@link UUID#fromString(String)}.
* Empty strings are treated as missing values, like blank cells.
*/
public class UuidStringConverter implements Converter<UUID> {

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The class name should remain UUIDStringConverter to stay consistent with Java’s standard java.util.UUID. There’s no need to use the Uuid variant.

public UUID convertToJavaData(
ReadCellData<?> cellData, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration) {
String value = cellData.getStringValue();
return value == null || value.isEmpty() ? null : UUID.fromString(value);

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To make the converter more robust, you might consider using StringUtils.isBlank(value) to handle null, empty, or whitespace-only strings, and then trim the value before parsing.
Something like UUID.fromString(value.trim()) would help avoid unexpected parsing failures caused by leading or trailing whitespace.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants