feat: add java.time.YearMonth converters

fesod-sheet/src/main/java/org/apache/fesod/sheet/converters/DefaultConverterLoader.java

@@ -78,6 +78,9 @@
 import org.apache.fesod.sheet.converters.string.StringNumberConverter;
 import org.apache.fesod.sheet.converters.string.StringStringConverter;
 import org.apache.fesod.sheet.converters.url.UrlImageConverter;
+import org.apache.fesod.sheet.converters.yearmonth.YearMonthDateConverter;
+import org.apache.fesod.sheet.converters.yearmonth.YearMonthNumberConverter;
+import org.apache.fesod.sheet.converters.yearmonth.YearMonthStringConverter;
 
 /**
  * Load default handler
@@ -114,6 +117,9 @@ private static void initAllConverter() {
         putAllConverter(new DateNumberConverter());
         putAllConverter(new DateStringConverter());
 
+        putAllConverter(new YearMonthNumberConverter());
+        putAllConverter(new YearMonthStringConverter());
+
         putAllConverter(new LocalDateNumberConverter());
         putAllConverter(new LocalDateStringConverter());
 
@@ -157,6 +163,7 @@ private static void initDefaultWriteConverter() {
         putWriteConverter(new BooleanBooleanConverter());
         putWriteConverter(new ByteNumberConverter());
         putWriteConverter(new DateDateConverter());
+        putWriteConverter(new YearMonthDateConverter());
         putWriteConverter(new LocalDateTimeDateConverter());
         putWriteConverter(new LocalDateDateConverter());
         putWriteConverter(new LocalTimeDateConverter());
@@ -178,6 +185,7 @@ private static void initDefaultWriteConverter() {
         putWriteStringConverter(new BooleanStringConverter());
         putWriteStringConverter(new ByteStringConverter());
         putWriteStringConverter(new DateStringConverter());
+        putWriteStringConverter(new YearMonthStringConverter());
         putWriteStringConverter(new LocalDateStringConverter());
         putWriteStringConverter(new LocalDateTimeStringConverter());
         putWriteStringConverter(new LocalTimeStringConverter());

fesod-sheet/src/main/java/org/apache/fesod/sheet/converters/yearmonth/YearMonthDateConverter.java

@@ -0,0 +1,61 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.fesod.sheet.converters.yearmonth;
+
+import java.time.YearMonth;
+import org.apache.fesod.sheet.converters.Converter;
+import org.apache.fesod.sheet.metadata.GlobalConfiguration;
+import org.apache.fesod.sheet.metadata.data.WriteCellData;
+import org.apache.fesod.sheet.metadata.property.ExcelContentProperty;
+import org.apache.fesod.sheet.util.WorkBookUtil;
+
+/**
+ * YearMonth and date converter
+ *
+ * <p>Excel has no month type, so a month is written as a date cell of the first day of that month, formatted with
+ * {@link #DEFAULT_FORMAT}, which keeps sorting and date arithmetic in the sheet working.
+ *
+ */
+public class YearMonthDateConverter implements Converter<YearMonth> {
+
+    /**
+     * Default format of a month cell
+     */
+    public static final String DEFAULT_FORMAT = "yyyy-MM";
+
+    @Override
+    public Class<YearMonth> supportJavaTypeKey() {
+        return YearMonth.class;
+    }
+
+    @Override
+    public WriteCellData<?> convertToExcelData(
+            YearMonth value, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration)
+            throws Exception {
+        WriteCellData<?> cellData =
+                new WriteCellData<>(value == null ? null : value.atDay(1).atStartOfDay());
+        String format = null;
+        if (contentProperty != null && contentProperty.getDateTimeFormatProperty() != null) {
+            format = contentProperty.getDateTimeFormatProperty().getFormat();
+        }
+        WorkBookUtil.fillDataFormat(cellData, format == null || format.isEmpty() ? null : format, DEFAULT_FORMAT);
+        return cellData;
+    }
+}

fesod-sheet/src/main/java/org/apache/fesod/sheet/converters/yearmonth/YearMonthNumberConverter.java

@@ -0,0 +1,66 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.fesod.sheet.converters.yearmonth;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.time.YearMonth;
+import org.apache.fesod.sheet.converters.Converter;
+import org.apache.fesod.sheet.enums.CellDataTypeEnum;
+import org.apache.fesod.sheet.metadata.GlobalConfiguration;
+import org.apache.fesod.sheet.metadata.data.ReadCellData;
+import org.apache.fesod.sheet.metadata.data.WriteCellData;
+import org.apache.fesod.sheet.metadata.property.ExcelContentProperty;
+import org.apache.fesod.sheet.util.DateUtils;
+import org.apache.poi.ss.usermodel.DateUtil;
+
+/**
+ * YearMonth and number converter
+ *
+ * <p>A month is read from and written to the first day of that month, so the value stays a real date in the sheet.
+ *
+ */
+public class YearMonthNumberConverter implements Converter<YearMonth> {
+
+    @Override
+    public Class<?> supportJavaTypeKey() {
+        return YearMonth.class;
+    }
+
+    @Override
+    public CellDataTypeEnum supportExcelTypeKey() {
+        return CellDataTypeEnum.NUMBER;
+    }
+
+    @Override
+    public YearMonth convertToJavaData(
+            ReadCellData<?> cellData, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration) {
+        LocalDate localDate = DateUtils.getLocalDate(
+                cellData.getNumberValue().doubleValue(), DateUtils.isDate1904(contentProperty, globalConfiguration));
+        return YearMonth.from(localDate);
+    }
+
+    @Override
+    public WriteCellData<?> convertToExcelData(
+            YearMonth value, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration) {
+        return new WriteCellData<>(BigDecimal.valueOf(DateUtil.getExcelDate(
+                value.atDay(1).atStartOfDay(), DateUtils.isDate1904(contentProperty, globalConfiguration))));
+    }
+}

fesod-sheet/src/main/java/org/apache/fesod/sheet/converters/yearmonth/YearMonthStringConverter.java

@@ -0,0 +1,90 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.fesod.sheet.converters.yearmonth;
+
+import java.time.YearMonth;
+import java.time.format.DateTimeFormatter;
+import java.util.Locale;
+import org.apache.fesod.common.util.StringUtils;
+import org.apache.fesod.sheet.converters.Converter;
+import org.apache.fesod.sheet.enums.CellDataTypeEnum;
+import org.apache.fesod.sheet.metadata.GlobalConfiguration;
+import org.apache.fesod.sheet.metadata.data.ReadCellData;
+import org.apache.fesod.sheet.metadata.data.WriteCellData;
+import org.apache.fesod.sheet.metadata.property.ExcelContentProperty;
+
+/**
+ * YearMonth and string converter
+ *
+ */
+public class YearMonthStringConverter implements Converter<YearMonth> {
+
+    @Override
+    public Class<?> supportJavaTypeKey() {
+        return YearMonth.class;
+    }
+
+    @Override
+    public CellDataTypeEnum supportExcelTypeKey() {
+        return CellDataTypeEnum.STRING;
+    }
+
+    @Override
+    public YearMonth convertToJavaData(
+            ReadCellData<?> cellData, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration) {
+        return YearMonth.parse(cellData.getStringValue(), formatter(contentProperty, globalConfiguration));
+    }
+
+    @Override
+    public WriteCellData<?> convertToExcelData(
+            YearMonth value, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration) {
+        return new WriteCellData<>(value.format(formatter(contentProperty, globalConfiguration)));
+    }
+
+    /**
+     * The formatter of the field, {@link YearMonthDateConverter#DEFAULT_FORMAT} when no format is set.
+     *
+     * <p>{@code @DateTimeFormat} defaults to an empty value and an empty pattern is not a usable one, so an empty
+     * format is handled like a missing one. The locale of the read or write is used, so a month name in the
+     * configured language can be parsed and written.
+     *
+     * @param contentProperty the property of the field
+     * @param globalConfiguration the configuration of the read or write, which carries the locale
+     * @return the formatter to use
+     */
+    private static DateTimeFormatter formatter(
+            ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration) {
+        String format = null;
+        if (contentProperty != null
+                && contentProperty.getDateTimeFormatProperty() != null
+                && StringUtils.isNotBlank(
+                        contentProperty.getDateTimeFormatProperty().getFormat())) {
+            format = contentProperty.getDateTimeFormatProperty().getFormat();
+        }
+        if (format == null) {
+            format = YearMonthDateConverter.DEFAULT_FORMAT;
+        }
+        Locale locale = globalConfiguration == null ? null : globalConfiguration.getLocale();
+        if (locale == null) {
+            return DateTimeFormatter.ofPattern(format);
+        }
+        return DateTimeFormatter.ofPattern(format, locale);
+    }
+}