IGNITE-26728 Add documentation for new interfaces and annotation types

Author: sergey-chugunov-1985

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

@@ -24,25 +24,16 @@
 
 /**
  * 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,
- * deserialized, or otherwise processed externally (e.g., to integer codes, strings, or other representations).
+ * It allows associating a custom mapper class that defines how enum constants are serialized and deserialized.
  *
- * <p>The class specified by {@link #value()} must implement the appropriate mapping interface
- * expected by the code generation framework, typically providing methods to convert between
- * enum constants and their external representations.</p>
+ * <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>Example usage:</p>
- * <pre>{@code
- * @CustomEnumMapper(className = "com.example.MyCustomColorMapper")
- * public enum Color {
- *     RED, GREEN, BLUE;
- * }
- * }</pre>
- *
- * <p>In this example, {@code MyCustomColorMapper} is responsible for defining the mapping logic
- * between the {@code Color} enum and its external form (e.g., integers or strings).</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)

modules/core/src/main/java/org/apache/ignite/plugin/extensions/communication/mappers/CustomMapper.java

@@ -17,21 +17,69 @@
 
 package org.apache.ignite.plugin.extensions.communication.mappers;
 
-/** */
+/**
+ * An interface to implement custom serialization and deserialization of enum values used in network communication.
+ *
+ * <p>This interface allows users to define a custom mapping between enum constants and their {@code byte}
+ * representations sent over the wire, instead of relying on the default ordinal-based encoding.
+ * It can be used in conjunction with the {@code org.apache.ignite.internal.CustomMapper} annotation
+ * to plug in user-defined mapping logic during generation of serialization code.</p>
+ *
+ * <p>Implementations must ensure that:
+ * <ul>
+ *     <li>Each enum constant maps to a unique {@code byte} value.</li>
+ *     <li>The {@code byte} codes are stable and consistent across all nodes in the cluster.</li>
+ *     <li>The {@link #decode(byte)} method handles invalid or unknown codes appropriately (e.g., throws an exception or returns a default).</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Example implementation:</p>
+ * <pre>{@code
+ * public class MyColorMapper implements CustomMapper<Color> {
+ *     public byte encode(Color color) {
+ *         switch (color) {
+ *             case null:  return -1;
+ *             case RED:   return 0;
+ *             case GREEN: return 1;
+ *             case BLUE:  return 2;
+ *             default:    throw new IllegalArgumentException("Unknown color: " + color);
+ *         }
+ *     }
+ *
+ *     public Color decode(byte code) {
+ *         switch (code) {
+ *             case -1: return null;
+ *             case 0: return Color.RED;
+ *             case 1: return Color.GREEN;
+ *             case 2: return Color.BLUE;
+ *             default: throw new IllegalArgumentException("Unknown color code: " + code);
+ *         }
+ *     }
+ * }
+ * }</pre>
+ *
+ * <p><strong>Note:</strong> This interface is used in Ignite's communication layer
+ * to enable evolution of enum types between different versions of the software.</p>
+ *
+ * @param <T> The enum type for which this mapper provides encoding/decoding logic.
+ * @see org.apache.ignite.internal.CustomMapper
+ * @see DefaultEnumMapper
+ */
 public interface CustomMapper<T extends Enum<T>> {
     /**
-     * Encodes enum value into {@code byte} representation that will be sent over the network.
+     * Encodes given enum value into a {@code byte} representation to be sent over the network.
      *
-     * @param val Value to encode.
-     * @return {@code byte} representation of the enum value.
+     * @param val The enum value to encode; may be {@code null} depending on implementation contract.
+     * @return The {@code byte} representation of the enum value.
      */
     public byte encode(T val);
 
     /**
-     * Decodes enum value from {@code byte} representation received from the network.
+     * Decodes a {@code byte} code received from the network into the corresponding enum constant.
      *
-     * @param code {@code byte} representation of the enum value.
-     * @return Decoded enum value.
+     * @param code The {@code byte} representation of the enum value.
+     * @return The decoded enum value.
+     * @throws IllegalArgumentException if the code does not correspond to any valid enum constant.
      */
     public T decode(byte code);
 }

modules/core/src/main/java/org/apache/ignite/plugin/extensions/communication/mappers/DefaultEnumMapper.java

@@ -17,7 +17,38 @@
 
 package org.apache.ignite.plugin.extensions.communication.mappers;
 
-/** */
+/**
+ * A default enum mapper that uses enum ordinal values to perform serialization and deserialization.
+ *
+ * <p>This mapper encodes an enum constant into a {@code byte} by taking its {@link Enum#ordinal()},
+ * and decodes a {@code byte} value back into the corresponding enum constant using array indexing.
+ * The encoding returns {@code -1} for {@code null} inputs, and decoding returns {@code null} for
+ * negative codes. If a provided code is out of range (greater than or equal to the number of enum
+ * constants), an {@link IllegalArgumentException} is thrown.</p>
+ *
+ * <p>This class assumes that:
+ * <ul>
+ *     <li>Enums have no more than 127 constants (to fit in a positive {@code byte}).</li>
+ *     <li>The order of enum constants (i.e., their ordinals) is stable and not subject to change.</li>
+ * </ul>
+ * </p>
+ *
+ * <p>Example usage:</p>
+ * <pre>{@code
+ * public enum Color {
+ *     RED, GREEN, BLUE;
+ * }
+ *
+ * Color[] values = Color.values();
+ * byte code = DefaultEnumMapper.INSTANCE.encode(Color.RED); // Returns 0
+ * Color color = DefaultEnumMapper.INSTANCE.decode(values, code); // Returns Color.RED
+ * }</pre>
+ *
+ * <p><strong>Note:</strong> This class is thread-safe and uses a singleton pattern.
+ * Use {@link #INSTANCE} to access the shared instance.</p>
+ *
+ * @see Enum#ordinal()
+ */
 public class DefaultEnumMapper {
     /** */
     public static final DefaultEnumMapper INSTANCE = new DefaultEnumMapper();
@@ -26,9 +57,11 @@ public class DefaultEnumMapper {
     private DefaultEnumMapper() {}
 
     /**
-     * @param <T> Enum type.
-     * @param enumVal Enum value to encode.
-     * @return {@code byte} representation of the enum value (non-negative) or {@code -1} if {@code null} value was provided.
+     * Encodes the given enum value into a {@code byte} using its ordinal.
+     *
+     * @param <T> The enum type.
+     * @param enumVal The enum value to encode; may be {@code null}.
+     * @return The {@code byte} representation of the enum value (non-negative) or {@code -1} if the value is {@code null}.
      */
     public <T extends Enum<T>> byte encode(T enumVal) {
         if (enumVal == null)
@@ -38,11 +71,14 @@ public <T extends Enum<T>> byte encode(T enumVal) {
     }
 
     /**
-     * @param <T> Enum type.
-     * @param vals Array of all possible values of the enum type. Should not be null.
-     * @param enumCode {@code byte} representation of enum value.
-     * @return Enum value or {@code null} if negative enumCode was provided.
-     * @throws IllegalArgumentException if enumCode is out of range.
+     * Decodes a {@code byte} code into the corresponding enum constant.
+     *
+     * @param <T> The enum type.
+     * @param vals Array of all possible values of the enum type. Must not be {@code null}.
+     * @param enumCode The {@code byte} representation of the enum value.
+     * @return The corresponding enum constant, or {@code null} if {@code enumCode} is negative.
+     * @throws IllegalArgumentException if {@code enumCode} is out of range
+     * (i.e., greater than or equal to the length of {@code vals} array).
      */
     public <T extends Enum<T>> T decode(T[] vals, byte enumCode) {
         if (enumCode < 0)

modules/core/src/test/java/org/apache/ignite/internal/managers/communication/DefaultEnumMapperTest.java

@@ -1,3 +1,20 @@
+/*
+ * 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.managers.communication;
 
 import org.apache.ignite.plugin.extensions.communication.mappers.DefaultEnumMapper;
@@ -8,7 +25,9 @@
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertNull;
 
-/** */
+/**
+ * Verifies behavior of {@link DefaultEnumMapper} on a single enum type.
+ */
 public class DefaultEnumMapperTest {
     /** */
     private final TransactionIsolation[] txIsolationVals = TransactionIsolation.values();