[Enhancement] Support @DictFormat annotation for code-label (dictionary) conversion

[nkuprins]

Search before asking

• I searched in the issues and found nothing similar.

Motivation

A field stores a code (1), the sheet should show a label (Success). Today that requires a hand-written Converter class per dictionary - there's no built-in way to declare a code↔label mapping on a field.

Solution

An annotation-based dictionary converter, @DictFormat, with an inline "code=label" form and an enum-backed form for dictionaries that already exist in the domain model.

Full design (API shape, field-type scope, validation rules, and two open questions) is written up here:
#198 (comment)
To avoid duplication, I will not repeat the same here.

I am open to changes. If this gets approved and someone answers the 2 questions mentioned there, then I can start gradually implementing that.

Alternatives

No response

Anything else?

Related: #198 (original request, Jan 2025)

Are you willing to submit a PR?

• I'm willing to submit a PR!

[nkuprins]

Thank you @MS-Jing, for #1006. I checked your use case against the @DictFormat design to see whether one feature covers both, and it does. However, the initial focus of @DictFormat was only on scalar types. Concretely:

Difference

Both start from "the field stores 1, the sheet should show Normal". They differ in what the Java field holds:

	#988	#1006
Field declaration	private Integer status;	private UserStatus status;
After a read, the field holds	1	UserStatus.NORMAL
Enum's role	supplies the mapping, if you have one	is the value

They fit in one annotation

// 1. scalar field, mapping used once
@DictFormat({"1=Success", "0=Failure"})
private Integer status;

// 2. scalar field, mapping already exists as an enum
@DictFormat(mapping = Status.class)          // Status implements Dict: code() + label()
private Integer status;

// 3. the field IS the enum
@DictFormat
private UserStatus status;                // UserStatus implements Labeled: label()

// 4. the field IS the enum, no annotation at all
private UserStatus status;

with two interfaces instead of one:

public interface Labeled { String label(); }
public interface Dict extends Labeled { String code(); }

The reason for 2 interfaces is that in 2. the enum has to say which scalar each constant stands for - that is code(). But in 3-4. the field stores the constant itself. There is no separate stored value for code() to describe, so only the label is needed.

Note: I changed @DictFormat(type = Status.class) to @DictFormat(mapping = Status.class) , because otherwise it is confusing.

[MS-Jing]

@nkuprins Thank you for your reply，I carefully read your proposal in #198

I think the fesod framework should not create the Dict interface.
Because the framework should not be concerned with the specific values of the business. This Dict interface should be created by the specific developers. Only in this way can the fesod framework be more pure.

// 1. scalar field, mapping used once
@DictFormat({"1=Success", "0=Failure"})
private Integer status;

// 2. scalar field, mapping already exists as an enum
@DictFormat(mapping = Status.class)          // Status implements Dict: code() + label()
private Integer status;

// 3. the field IS the enum
@DictFormat
private UserStatus status;                // UserStatus implements Labeled: label()

// 4. the field IS the enum, no annotation at all
private UserStatus status;

• In 1, This DictFormat annotation will have some of the validation issues you mentioned in #198 .
• In 2, This @DictFormat(mapping = Status.class) annotation is equivalent to the @ExcelProperty(converter = IEnumConverter.class). annotation. And there is no need to pay attention to the specific Status.class.
• In 3, This DictFormat annotation is merely a label.
• In 4, No other unnecessary annotations. It is more acceptable to business developers and reduces their psychological burden.They only need to implement the Labeled interface for their business enumerations, and then they can handle the values of the enumeration types just like basic data types.

So, I think the @DictFormat annotation is not mandatory.

As I mentioned in #1006 . Only two files need to be modified and two more files need to be added.

public interface Labeled {
    String getLabel();
}

public class IEnumConverter implements Converter<Labeled> {

    private static final Map<Class<?>, List<Labeled>> enumCache = new HashMap<>();

    @Override
    public Class<?> supportJavaTypeKey() {
        return Labeled.class;
    }

    @Override
    public CellDataTypeEnum supportExcelTypeKey() {
        return CellDataTypeEnum.STRING;
    }

    @Override
    public WriteCellData<?> convertToExcelData(Labeled value, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration) throws Exception {
        if (value != null) {
            return new WriteCellData<>(value.getLabel());
        }
        return new WriteCellData<>();
    }

    @Override
    public Labeled convertToJavaData(ReadCellData<?> cellData, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration) throws Exception {
        Class<?> type = contentProperty.getField().getType();
        if (!enumCache.containsKey(type)) {
            Object[] enumConstants = type.getEnumConstants();
            List<Labeled> labeledList = Arrays.stream(enumConstants).map(enumConstant -> (Labeled) enumConstant).collect(Collectors.toList());
            enumCache.put(type, labeledList);
        }
        List<Labeled> labeledList = enumCache.getOrDefault(type, Collections.emptyList());
        for (Labeled labeled : labeledList) {
            if (labeled.getLabel().equals(cellData.getStringValue())) {
                return labeled;
            }
        }
        return null;
    }
}

modification ConverterKeyBuild#buildKey:

 public static ConverterKey buildKey(Class<?> clazz, CellDataTypeEnum cellDataTypeEnum) {
      Class<?> boxingClass = BOXING_MAP.get(clazz);
      if (boxingClass != null) {
          return new ConverterKey(boxingClass, cellDataTypeEnum);
      }
      if (clazz == Labeled.class || (clazz.isEnum() && Labeled.class.isAssignableFrom(clazz))) {
          // clazz equals IEnum.class or clazz is enum and IEnum is assignable from clazz
          return new ConverterKey(Labeled.class, cellDataTypeEnum);
      }
      return new ConverterKey(clazz, cellDataTypeEnum);
  }

modification DefaultConverterLoader#initDefaultWriteConverter and DefaultConverterLoader#initAllConverter:

    private static void initAllConverter() {
        ......
        putAllConverter(new IEnumConverter());
    }

    private static void initDefaultWriteConverter() {
         ......
        putWriteConverter(new IEnumConverter());
        ......
        putWriteStringConverter(new IEnumConverter());
    }

Business developers only need to handle the business enumerations properly and can use it normally without performing any other operations.

@Test
    public void testLabeledConverter() {
        String fileName = System.getProperty("user.dir") + "/iEnumConverter.xlsx";

        // 写出枚举类型字段
        FastExcel.write(fileName)
            .head(UserInfo.class)
            .sheet()
            .doWrite(testDataList());

        // 读取枚举类型字段
        List<UserInfo> list = FastExcel.read(fileName)
            .head(UserInfo.class)
            .sheet()
            .doReadSync();
        System.out.println(list);
    }

I am more than willing to submit the PR. Looking forward to your reply

My English is not very good. It's all translated by software. If there are any mistakes, please correct them. thanks again

[MS-Jing]

Hi！ @nkuprins Sorry to bother you.
Can I submit this pull request? I have written unit tests to ensure the rationality of the changes and the consistency of the style.
If possible, could I work on that branch? Main or dev-word-branch? Because after I forked, I found that the fesod-shaded files in these two branches were empty, which caused a compilation error.
Do you have any other suggestions?
Looking forward to your reply!
Thank you very much!

[nkuprins]

Hi @MS-Jing, no bother at all. I would suggest that you wait for permission from the maintainers before submitting this PR, as this is a new feature. I currently don't feel like there is a consensus on the final approach and think it's better to wait for the maintainers to express their vision. If there is some disagreement, it's better to resolve it before writing code to save time for you and for the reviewer. Note that the community is currently busy with the upcoming release, and according to my knowledge, the priority is to merge PR that fix bugs, so you may have to wait a little.

@delei could you please reply to him, when convenient for you? :)

[MS-Jing]

@nkuprins
OK, thank you for your reply! I can wait until the new version is released before we proceed with the discussion.