feat: add java.time.OffsetDateTime converters (#1017)

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

@@ -70,6 +70,9 @@
 import org.apache.fesod.sheet.converters.longconverter.LongBooleanConverter;
 import org.apache.fesod.sheet.converters.longconverter.LongNumberConverter;
 import org.apache.fesod.sheet.converters.longconverter.LongStringConverter;
+import org.apache.fesod.sheet.converters.offsetdatetime.OffsetDateTimeDateConverter;
+import org.apache.fesod.sheet.converters.offsetdatetime.OffsetDateTimeNumberConverter;
+import org.apache.fesod.sheet.converters.offsetdatetime.OffsetDateTimeStringConverter;
 import org.apache.fesod.sheet.converters.shortconverter.ShortBooleanConverter;
 import org.apache.fesod.sheet.converters.shortconverter.ShortNumberConverter;
 import org.apache.fesod.sheet.converters.shortconverter.ShortStringConverter;
@@ -122,6 +125,8 @@ private static void initAllConverter() {
 
         putAllConverter(new LocalTimeNumberConverter());
         putAllConverter(new LocalTimeStringConverter());
+        putAllConverter(new OffsetDateTimeNumberConverter());
+        putAllConverter(new OffsetDateTimeStringConverter());
 
         putAllConverter(new DoubleBooleanConverter());
         putAllConverter(new DoubleNumberConverter());
@@ -160,6 +165,7 @@ private static void initDefaultWriteConverter() {
         putWriteConverter(new LocalDateTimeDateConverter());
         putWriteConverter(new LocalDateDateConverter());
         putWriteConverter(new LocalTimeDateConverter());
+        putWriteConverter(new OffsetDateTimeDateConverter());
         putWriteConverter(new DoubleNumberConverter());
         putWriteConverter(new FloatNumberConverter());
         putWriteConverter(new IntegerNumberConverter());
@@ -181,6 +187,7 @@ private static void initDefaultWriteConverter() {
         putWriteStringConverter(new LocalDateStringConverter());
         putWriteStringConverter(new LocalDateTimeStringConverter());
         putWriteStringConverter(new LocalTimeStringConverter());
+        putWriteStringConverter(new OffsetDateTimeStringConverter());
         putWriteStringConverter(new DoubleStringConverter());
         putWriteStringConverter(new FloatStringConverter());
         putWriteStringConverter(new IntegerStringConverter());

fesod-sheet/src/main/java/org/apache/fesod/sheet/converters/offsetdatetime/OffsetDateTimeDateConverter.java

@@ -0,0 +1,55 @@
+/*
+ * 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.offsetdatetime;
+
+import java.time.LocalDateTime;
+import java.time.OffsetDateTime;
+import org.apache.fesod.common.util.StringUtils;
+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.DateUtils;
+import org.apache.fesod.sheet.util.WorkBookUtil;
+
+/** OffsetDateTime and date converter. */
+public class OffsetDateTimeDateConverter implements Converter<OffsetDateTime> {
+    @Override
+    public Class<?> supportJavaTypeKey() {
+        return OffsetDateTime.class;
+    }
+
+    @Override
+    public WriteCellData<?> convertToExcelData(
+            OffsetDateTime value, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration)
+            throws Exception {
+        LocalDateTime localDateTime = value.toLocalDateTime();
+        WriteCellData<?> cellData = new WriteCellData<>(localDateTime);
+        String format = null;
+        if (contentProperty != null && contentProperty.getDateTimeFormatProperty() != null) {
+            format = contentProperty.getDateTimeFormatProperty().getFormat();
+            if (StringUtils.isEmpty(format)) {
+                format = null;
+            }
+        }
+        WorkBookUtil.fillDataFormat(cellData, format, DateUtils.defaultDateFormat);
+        return cellData;
+    }
+}

fesod-sheet/src/main/java/org/apache/fesod/sheet/converters/offsetdatetime/OffsetDateTimeNumberConverter.java

@@ -0,0 +1,64 @@
+/*
+ * 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.offsetdatetime;
+
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+import java.time.OffsetDateTime;
+import java.time.ZoneId;
+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;
+
+/** OffsetDateTime and number converter. */
+public class OffsetDateTimeNumberConverter implements Converter<OffsetDateTime> {
+    @Override
+    public Class<?> supportJavaTypeKey() {
+        return OffsetDateTime.class;
+    }
+
+    @Override
+    public CellDataTypeEnum supportExcelTypeKey() {
+        return CellDataTypeEnum.NUMBER;
+    }
+
+    @Override
+    public OffsetDateTime convertToJavaData(
+            ReadCellData<?> cellData, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration) {
+        LocalDateTime localDateTime = DateUtils.getLocalDateTime(
+                cellData.getNumberValue().doubleValue(), DateUtils.isDate1904(contentProperty, globalConfiguration));
+        if (localDateTime == null) {
+            return null;
+        }
+        return localDateTime.atZone(ZoneId.systemDefault()).toOffsetDateTime();
+    }
+
+    @Override
+    public WriteCellData<?> convertToExcelData(
+            OffsetDateTime value, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration) {
+        return new WriteCellData<>(BigDecimal.valueOf(DateUtil.getExcelDate(
+                value.toLocalDateTime(), DateUtils.isDate1904(contentProperty, globalConfiguration))));
+    }
+}

fesod-sheet/src/main/java/org/apache/fesod/sheet/converters/offsetdatetime/OffsetDateTimeStringConverter.java

@@ -0,0 +1,62 @@
+/*
+ * 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.offsetdatetime;
+
+import java.time.OffsetDateTime;
+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;
+
+/** OffsetDateTime and string converter. */
+public class OffsetDateTimeStringConverter implements Converter<OffsetDateTime> {
+    @Override
+    public Class<?> supportJavaTypeKey() {
+        return OffsetDateTime.class;
+    }
+
+    @Override
+    public CellDataTypeEnum supportExcelTypeKey() {
+        return CellDataTypeEnum.STRING;
+    }
+
+    @Override
+    public OffsetDateTime convertToJavaData(
+            ReadCellData<?> cellData, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration) {
+        return DateUtils.parseOffsetDateTime(
+                cellData.getStringValue(), format(contentProperty), globalConfiguration.getLocale());
+    }
+
+    @Override
+    public WriteCellData<?> convertToExcelData(
+            OffsetDateTime value, ExcelContentProperty contentProperty, GlobalConfiguration globalConfiguration) {
+        return new WriteCellData<>(DateUtils.format(value, format(contentProperty), globalConfiguration.getLocale()));
+    }
+
+    private String format(ExcelContentProperty contentProperty) {
+        if (contentProperty == null || contentProperty.getDateTimeFormatProperty() == null) {
+            return null;
+        }
+        return contentProperty.getDateTimeFormatProperty().getFormat();
+    }
+}

fesod-sheet/src/main/java/org/apache/fesod/sheet/util/DateUtils.java

@@ -32,6 +32,7 @@
 import java.time.LocalDate;
 import java.time.LocalDateTime;
 import java.time.LocalTime;
+import java.time.OffsetDateTime;
 import java.time.format.DateTimeFormatter;
 import java.util.Calendar;
 import java.util.Date;
@@ -164,6 +165,21 @@ public static LocalTime parseLocalTime(String timeString, String timeFormat, Loc
         return LocalTime.parse(timeString, getCacheDateTimeFormat(timeFormat, local));
     }
 
+    /**
+     * convert string to date, requiring the string to carry an explicit offset
+     *
+     * @param dateString date string, e.g. 2020-01-02T03:04:05+08:00
+     * @param dateFormat date format, empty means ISO_OFFSET_DATE_TIME
+     * @param local local
+     * @return
+     */
+    public static OffsetDateTime parseOffsetDateTime(String dateString, String dateFormat, Locale local) {
+        if (StringUtils.isEmpty(dateFormat)) {
+            return OffsetDateTime.parse(dateString, DateTimeFormatter.ISO_OFFSET_DATE_TIME);
+        }
+        return OffsetDateTime.parse(dateString, getCacheDateTimeFormat(dateFormat, local));
+    }
+
     /**
      * convert string to date
      *
@@ -328,6 +344,24 @@ public static String format(LocalTime time, String timeFormat, Locale local) {
         return time.format(getCacheDateTimeFormat(timeFormat, local));
     }
 
+    /**
+     * Format date, preserving the offset in the output
+     *
+     * @param date date
+     * @param dateFormat date format, empty means ISO_OFFSET_DATE_TIME
+     * @param local local
+     * @return format string
+     */
+    public static String format(OffsetDateTime date, String dateFormat, Locale local) {
+        if (date == null) {
+            return null;
+        }
+        if (StringUtils.isEmpty(dateFormat)) {
+            return date.format(DateTimeFormatter.ISO_OFFSET_DATE_TIME);
+        }
+        return date.format(getCacheDateTimeFormat(dateFormat, local));
+    }
+
     /**
      * Format date
      *