IGNITE-26728 Perform enum fields serialization/deserialization with external mappers (#12554)

Author: sergey-chugunov-1985

modules/codegen2/src/main/java/org/apache/ignite/internal/CustomMapper.java

@@ -0,0 +1,51 @@
+/*
+ * 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.ignite.internal;
+
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation used to specify a custom mapping strategy for an enum type during code generation.
+ * It allows associating a custom mapper class that defines how enum constants are serialized and deserialized.
+ *
+ * <p>It is used in conjunction with {@link Order} annotation and used to mark fields of enum type
+ * that should be serialized and deserialized using custom logic.</p>
+ *
+ * <p>The class specified by {@link #value()} must implement {@code org.apache.ignite.plugin.extensions.communication.mappers.CustomMapper}
+ * interface to provide methods for converting enum values to and from their external representations.</p>
+ *
+ * @see #value()
+ * @see org.apache.ignite.internal.Order
+ */
+@Retention(RetentionPolicy.CLASS)
+@Target(ElementType.FIELD)
+public @interface CustomMapper {
+    /**
+     * Returns the fully qualified class name of the custom mapper implementation
+     * used to handle the enum's value conversion.
+     *
+     * <p>The specified class must be available on the classpath during code generation
+     * and must adhere to the expected mapper interface contract.</p>
+     *
+     * @return The fully qualified name of the mapper class. Must not be null or empty.
+     */
+    String value() default "";
+}

modules/codegen2/src/main/java/org/apache/ignite/internal/MessageProcessor.java

@@ -34,9 +34,14 @@
 import javax.lang.model.element.Modifier;
 import javax.lang.model.element.TypeElement;
 import javax.lang.model.element.VariableElement;
+import javax.lang.model.type.TypeKind;
 import javax.lang.model.type.TypeMirror;
 import javax.tools.Diagnostic;
 
+import org.apache.ignite.lang.IgniteBiTuple;
+
+import static org.apache.ignite.internal.MessageSerializerGenerator.DLFT_ENUM_MAPPER_CLS;
+
 /**
  * Annotation processor that generates serialization and deserialization code for classes implementing the {@code Message} interface.
  * <p>
@@ -71,6 +76,9 @@ public class MessageProcessor extends AbstractProcessor {
     /** This is the only message with zero fields. A serializer must be generated due to restrictions in our communication process. */
     static final String HANDSHAKE_WAIT_MESSAGE = "org.apache.ignite.spi.communication.tcp.messages.HandshakeWaitMessage";
 
+    /** */
+    private final Map<String, IgniteBiTuple<String, String>> enumMappersInUse = new HashMap<>();
+
     /**
      * Processes all classes implementing the {@code Message} interface and generates corresponding serializer code.
      */
@@ -132,9 +140,11 @@ private List<VariableElement> orderedFields(TypeElement type) {
                     if (el.getModifiers().contains(Modifier.STATIC)) {
                         processingEnv.getMessager().printMessage(
                             Diagnostic.Kind.ERROR,
-                            "Annotation @Order must be used only for non-static fields.",
+                            "Annotation @Order must only be used for non-static fields.",
                             el);
                     }
+
+                    validateEnumFieldMapping(type, el);
                 }
             }
 
@@ -156,4 +166,54 @@ private List<VariableElement> orderedFields(TypeElement type) {
 
         return result;
     }
+
+    /**
+     * Validates consistency of enum field mappers configuration: the same mapper is used for the same enum in different messages,
+     * CustomMapper annotation is used only for enum fields.
+     *
+     * @param type Type implementing Message interface.
+     * @param el Enclosed element of the type.
+     */
+    private void validateEnumFieldMapping(TypeElement type, Element el) {
+        CustomMapper custMappAnn = el.getAnnotation(CustomMapper.class);
+        if (isEnumField(el)) {
+            String enumClsFullName = el.asType().toString();
+            String enumMapperClsName = custMappAnn != null ? custMappAnn.value() : DLFT_ENUM_MAPPER_CLS;
+            String msgClsName = type.toString();
+
+            IgniteBiTuple<String, String> otherMsgAndMapperClassesNames =
+                enumMappersInUse.put(enumClsFullName, new IgniteBiTuple<>(msgClsName, enumMapperClsName));
+
+            if (otherMsgAndMapperClassesNames != null) {
+                String otherMsgClsName = otherMsgAndMapperClassesNames.get1();
+                String otherEnumMapperClsName = otherMsgAndMapperClassesNames.get2();
+
+                if (!otherEnumMapperClsName.equals(enumMapperClsName)) {
+                    processingEnv.getMessager().printMessage(
+                        Diagnostic.Kind.ERROR,
+                        "Enum " + enumClsFullName + " is declared with different mappers: " +
+                            otherEnumMapperClsName + " in " + otherMsgClsName + " and " +
+                            enumMapperClsName + " in " + msgClsName +
+                            ". Only one mapper is allowed per enum type.",
+                        el);
+                }
+            }
+        }
+        else if (custMappAnn != null) {
+            processingEnv.getMessager().printMessage(
+                Diagnostic.Kind.ERROR,
+                "Annotation @CustomMapper must only be used for enum fields.",
+                el);
+        }
+    }
+
+    /** */
+    private boolean isEnumField(Element el) {
+        TypeMirror elType = el.asType();
+
+        if (elType.getKind() != TypeKind.DECLARED)
+            return false;
+
+        return processingEnv.getTypeUtils().asElement(elType).getKind() == ElementKind.ENUM;
+    }
 }

modules/codegen2/src/main/java/org/apache/ignite/internal/MessageSerializerGenerator.java

@@ -83,6 +83,12 @@ class MessageSerializerGenerator {
     /** */
     private static final String METHOD_JAVADOC = "/** */";
 
+    /** */
+    private static final String RETURN_FALSE_STMT = "return false;";
+
+    /** */
+    static final String DLFT_ENUM_MAPPER_CLS = "org.apache.ignite.plugin.extensions.communication.mappers.DefaultEnumMapper";
+
     /** Collection of lines for {@code writeTo} method. */
     private final List<String> write = new ArrayList<>();
 
@@ -92,6 +98,9 @@ class MessageSerializerGenerator {
     /** Collection of message-specific imports. */
     private final Set<String> imports = new TreeSet<>();
 
+    /** Collection of Serializer class fields containing mappers for message enum fields. */
+    private final Set<String> fields = new TreeSet<>();
+
     /** */
     private final ProcessingEnvironment env;
 
@@ -142,6 +151,8 @@ private String generateSerializerCode(String serClsName) throws IOException {
         try (Writer writer = new StringWriter()) {
             writeClassHeader(writer, PKG_NAME, serClsName);
 
+            writeClassFields(writer);
+
             // Write #writeTo method.
             for (String w: write)
                 writer.write(w + NL);
@@ -238,10 +249,6 @@ private void processField(VariableElement field, int opt) throws Exception {
         if (assignableFrom(field.asType(), type(Throwable.class.getName())))
             throw new UnsupportedOperationException("You should use ErrorMessage for serialization of throwables.");
 
-        if (enumType(erasedType(field.asType())))
-            throw new IllegalArgumentException("Unsupported enum type: " + field.asType() +
-                    ". The enum must be wrapped into a Message (see, for example, TransactionIsolationMessage).");
-
         writeField(field, opt);
         readField(field, opt);
     }
@@ -396,6 +403,45 @@ else if (assignableFrom(erasedType(type), type(Collection.class.getName()))) {
                     "MessageCollectionItemType." + messageCollectionItemType(typeArgs.get(0)));
             }
 
+            else if (enumType(type)) {
+                Element element = env.getTypeUtils().asElement(type);
+                imports.add(element.toString());
+
+                String enumName = element.getSimpleName().toString();
+                String enumFieldPrefix = typeNameToFieldName(enumName);
+
+                String mapperCallStmnt;
+
+                CustomMapper custMapperAnn = field.getAnnotation(CustomMapper.class);
+
+                if (custMapperAnn != null) {
+                    String fullMapperName = custMapperAnn.value();
+                    if (fullMapperName == null || fullMapperName.isEmpty())
+                        throw new IllegalArgumentException("Please specify a not-null not-empty EnumMapper class name");
+
+                    imports.add("org.apache.ignite.plugin.extensions.communication.mappers.EnumMapper");
+                    imports.add(fullMapperName);
+
+                    String simpleName = fullMapperName.substring(fullMapperName.lastIndexOf('.') + 1);
+
+                    String mapperFieldName = enumFieldPrefix + "Mapper";
+
+                    fields.add("private final EnumMapper<" + enumName + "> " + mapperFieldName + " = new " + simpleName + "();");
+
+                    mapperCallStmnt = mapperFieldName + ".encode";
+                }
+                else {
+                    imports.add(DLFT_ENUM_MAPPER_CLS);
+                    String enumValuesFieldName = enumFieldPrefix + "Vals";
+
+                    fields.add("private final " + enumName + "[] " + enumValuesFieldName + " = " + enumName + ".values();");
+
+                    mapperCallStmnt = "DefaultEnumMapper.INSTANCE.encode";
+                }
+
+                returnFalseIfEnumWriteFailed(write, "writer.writeByte", mapperCallStmnt, getExpr);
+            }
+
             else
                 throw new IllegalArgumentException("Unsupported declared type: " + type);
 
@@ -405,6 +451,15 @@ else if (assignableFrom(erasedType(type), type(Collection.class.getName()))) {
         throw new IllegalArgumentException("Unsupported type kind: " + type.getKind());
     }
 
+    /**
+     * Converts type name to camel case field name. Example: {@code "MyType"} -> {@code "myType"}.
+     */
+    private String typeNameToFieldName(String typeName) {
+        char[] typeNameChars = typeName.toCharArray();
+        typeNameChars[0] = Character.toLowerCase(typeNameChars[0]);
+        return new String(typeNameChars);
+    }
+
     /**
      * Generate code of writing single field:
      * <pre>
@@ -419,7 +474,24 @@ private void returnFalseIfWriteFailed(Collection<String> code, String accessor,
 
         indent++;
 
-        code.add(line("return false;"));
+        code.add(line(RETURN_FALSE_STMT));
+
+        indent--;
+    }
+
+    /**
+     * Generate code of writing single enum field mapped with EnumMapper:
+     * <pre>
+     * if (!writer.writeByte(myEnumMapper.encode(msg.myEnum()))
+     *     return false;
+     * </pre>
+     */
+    private void returnFalseIfEnumWriteFailed(Collection<String> code, String writerCall, String mapperCall, String fieldGetterCall) {
+        code.add(line("if (!%s(%s(msg.%s)))", writerCall, mapperCall, fieldGetterCall));
+
+        indent++;
+
+        code.add(line(RETURN_FALSE_STMT));
 
         indent--;
     }
@@ -538,6 +610,17 @@ else if (assignableFrom(erasedType(type), type(Collection.class.getName()))) {
                     "MessageCollectionItemType." + messageCollectionItemType(typeArgs.get(0)));
             }
 
+            else if (enumType(type)) {
+                String fieldPrefix = typeNameToFieldName(env.getTypeUtils().asElement(type).getSimpleName().toString());
+
+                boolean hasCustMapperAnn = field.getAnnotation(CustomMapper.class) != null;
+
+                String mapperCallStmnt = hasCustMapperAnn ? fieldPrefix + "Mapper.decode" : "DefaultEnumMapper.INSTANCE.decode";
+                String enumValsFieldName = hasCustMapperAnn ? null : fieldPrefix + "Vals";
+
+                returnFalseIfEnumReadFailed(name, mapperCallStmnt, enumValsFieldName);
+            }
+
             else
                 throw new IllegalArgumentException("Unsupported declared type: " + type);
 
@@ -646,7 +729,36 @@ private void returnFalseIfReadFailed(String var, String mtd, String... args) {
 
         indent++;
 
-        read.add(line("return false;"));
+        read.add(line(RETURN_FALSE_STMT));
+
+        indent--;
+    }
+
+    /**
+     * Generate code of reading single field:
+     * <pre>
+     * msg.id(reader.readInt());
+     *
+     * if (!reader.isLastRead())
+     *     return false;
+     * </pre>
+     *
+     * @param msgSetterName Variable name.
+     * @param mapperDecodeCallStmnt Method name.
+     */
+    private void returnFalseIfEnumReadFailed(String msgSetterName, String mapperDecodeCallStmnt, String enumValuesFieldName) {
+        if (enumValuesFieldName == null)
+            read.add(line("msg.%s(%s(reader.readByte()));", msgSetterName, mapperDecodeCallStmnt));
+        else
+            read.add(line("msg.%s(%s(%s, reader.readByte()));", msgSetterName, mapperDecodeCallStmnt, enumValuesFieldName));
+
+        read.add(EMPTY);
+
+        read.add(line("if (!reader.isLastRead())"));
+
+        indent++;
+
+        read.add(line(RETURN_FALSE_STMT));
 
         indent--;
     }
@@ -680,6 +792,24 @@ private String line(String format, Object... args) {
         return sb.toString();
     }
 
+    /** Write serializer class fields: enum values, custom enum mappers. */
+    private void writeClassFields(Writer writer) throws IOException {
+        if (fields.isEmpty())
+            return;
+
+        indent = 1;
+
+        for (String field: fields) {
+            writer.write(line(METHOD_JAVADOC));
+            writer.write(NL);
+            writer.write(line(field));
+            writer.write(NL);
+        }
+        writer.write(NL);
+
+        indent = 0;
+    }
+
     /** Write header of serializer class: license, imports, class declaration. */
     private void writeClassHeader(Writer writer, String pkgName, String serClsName) throws IOException {
         try (InputStream in = getClass().getClassLoader().getResourceAsStream("license.txt");
@@ -701,8 +831,8 @@ private void writeClassHeader(Writer writer, String pkgName, String serClsName)
         imports.add("org.apache.ignite.plugin.extensions.communication.MessageWriter");
         imports.add("org.apache.ignite.plugin.extensions.communication.MessageReader");
 
-        for (String i: imports)
-            writer.write("import " + i + ";" + NL);
+        for (String regularImport: imports)
+            writer.write("import " + regularImport + ";" + NL);
 
         writer.write(NL);
         writer.write(CLS_JAVADOC);
@@ -727,13 +857,9 @@ private boolean assignableFrom(TypeMirror type, TypeMirror superType) {
 
     /** */
     private boolean enumType(TypeMirror type) {
-        if (type.getKind() == TypeKind.DECLARED) {
-            Element element = env.getTypeUtils().asElement(type);
+        Element element = env.getTypeUtils().asElement(type);
 
-            return element != null && element.getKind() == ElementKind.ENUM;
-        }
-
-        return false;
+        return element != null && element.getKind() == ElementKind.ENUM;
     }
 
     /** */

modules/core/pom.xml

@@ -387,6 +387,10 @@
                     <annotationProcessors>
                         <annotationProcessor>org.apache.ignite.internal.MessageProcessor</annotationProcessor>
                     </annotationProcessors>
+                    <compilerArgs combine.children="append">
+                        <arg>-Xmaxerrs</arg>
+                        <arg>1000</arg>
+                    </compilerArgs>
                 </configuration>
             </plugin>
         </plugins>