refactor: support xlang ref

Author: kaori-seasons

java/fory-core/src/test/java/org/apache/fory/RustXlangTest.java

@@ -127,6 +127,8 @@ public void testRust() throws Exception {
     testStructVersionCheck(Language.RUST, command);
     command.set(RUST_TESTCASE_INDEX, "test_consistent_named");
     testConsistentNamed(Language.RUST, command);
+    command.set(RUST_TESTCASE_INDEX, "test_reference_alignment");
+    testReferenceAlignment(Language.RUST, command);
   }
 
   private void testBuffer(Language language, List<String> command) throws IOException {
@@ -941,4 +943,79 @@ private void assertStringEquals(Object actual, Object expected, boolean useToStr
       Assert.assertEquals(actual, expected);
     }
   }
+
+  /**
+   * Test reference type alignment between Java and Rust in xlang mode.
+   *
+   * <p>This test verifies that:
+   * <ul>
+   *   <li>Primitive types (int, double, boolean) don't write RefFlag
+   *   <li>Reference types (String, List, Map) write RefFlag in xlang mode
+   *   <li>Rust-serialized data can be correctly deserialized in Java
+   *   <li>Java-serialized data can be correctly deserialized in Rust
+   * </ul>
+   */
+  private void testReferenceAlignment(Language language, List<String> command)
+      throws IOException {
+    Fory fory = Fory.builder()
+        .withLanguage(Language.XLANG)
+        .withCompatibleMode(CompatibleMode.COMPATIBLE)
+        .build();
+
+    // Serialize test data from Java
+    MemoryBuffer buffer = MemoryBuffer.newHeapBuffer(256);
+
+    // 1. Primitive int (no RefFlag)
+    fory.serialize(buffer, 42);
+
+    // 2. Boxed Integer (with RefFlag for null handling)
+    fory.serialize(buffer, Integer.valueOf(100));
+
+    // 3. String (reference type, with RefFlag)
+    fory.serialize(buffer, "hello");
+
+    // 4. List<String> (reference type, with RefFlag)
+    fory.serialize(buffer, Arrays.asList("a", "b"));
+
+    // 5. Map<String, Integer> (reference type, with RefFlag)
+    Map<String, Integer> map = new HashMap<>();
+    map.put("key1", 10);
+    map.put("key2", 20);
+    fory.serialize(buffer, map);
+
+    // 6. Double (primitive, no RefFlag)
+    fory.serialize(buffer, 3.14);
+
+    // 7. Boolean (primitive, no RefFlag)
+    fory.serialize(buffer, true);
+
+    byte[] bytes = buffer.getBytes(0, buffer.writerIndex());
+    LOG.info("Java serialized {} bytes for reference alignment test", bytes.length);
+
+    // Send to Rust for verification
+    Path dataFile = Files.createTempFile("test_reference_alignment", "data");
+    Pair<Map<String, String>, File> env_workdir = setFilePath(language, command, dataFile, bytes);
+    Assert.assertTrue(
+        executeCommand(command, 30, env_workdir.getLeft(), env_workdir.getRight()),
+        "Rust test failed");
+
+    // Read back Rust's serialization and verify
+    MemoryBuffer buffer2 = MemoryUtils.wrap(Files.readAllBytes(dataFile));
+
+    Assert.assertEquals(fory.deserialize(buffer2), 42, "i32 value mismatch");
+    Assert.assertEquals(fory.deserialize(buffer2), Integer.valueOf(100), "Option<i32> value mismatch");
+    Assert.assertEquals(fory.deserialize(buffer2), "hello", "String value mismatch");
+    Assert.assertEquals(
+        fory.deserialize(buffer2), Arrays.asList("a", "b"), "Vec<String> value mismatch");
+
+    @SuppressWarnings("unchecked")
+    Map<String, Integer> deserializedMap = (Map<String, Integer>) fory.deserialize(buffer2);
+    Assert.assertEquals(deserializedMap.get("key1"), Integer.valueOf(10), "HashMap key1 mismatch");
+    Assert.assertEquals(deserializedMap.get("key2"), Integer.valueOf(20), "HashMap key2 mismatch");
+
+    Assert.assertEquals(fory.deserialize(buffer2), 3.14, "f64 value mismatch");
+    Assert.assertEquals(fory.deserialize(buffer2), true, "bool value mismatch");
+
+    LOG.info("Reference alignment test passed!");
+  }
 }

rust/fory-core/src/serializer/core.rs

@@ -258,8 +258,21 @@ pub trait Serializer: 'static {
         Self: Sized,
     {
         if write_ref_info {
-            // skip check option/pointer, the Serializer for such types will override `fory_write`.
-            context.writer.write_i8(RefFlag::NotNullValue as i8);
+            // In xlang mode, determine RefFlag based on type characteristics
+            let should_write_ref = if context.is_xlang() {
+                Self::fory_is_xlang_ref_type()
+            } else {
+                // In non-xlang mode, use original logic
+                true
+            };
+            
+            if should_write_ref {
+                // This is a reference type in xlang context - write RefValue
+                context.writer.write_i8(RefFlag::RefValue as i8);
+            } else {
+                // This is a value type - write NotNullValue
+                context.writer.write_i8(RefFlag::NotNullValue as i8);
+            }
         }
         if write_type_info {
             // Serializer for dynamic types should override `fory_write` to write actual typeinfo.
@@ -1217,6 +1230,70 @@ pub trait Serializer: 'static {
         std::mem::size_of::<Self>()
     }
 
+    /// Indicate whether this type should be treated as a reference type in cross-language (xlang) serialization.
+    ///
+    /// In cross-language scenarios, type systems differ between languages. For example:
+    /// - In Java: `String`, `List`, `Map` are reference types (need RefFlag)
+    /// - In Rust: `String`, `Vec`, `HashMap` are value types (by default, no RefFlag)
+    ///
+    /// This method bridges the gap by allowing Rust types to declare their cross-language reference semantics.
+    ///
+    /// # Returns
+    ///
+    /// - `true` if this type should be treated as a reference type in xlang mode
+    ///   (will write RefFlag during serialization)
+    /// - `false` if this type should be treated as a value type in xlang mode
+    ///   (will not write RefFlag, default)
+    ///
+    /// # Type Mapping Guidelines
+    ///
+    /// | Rust Type | Java Type | Should Return |
+    /// |-----------|-----------|---------------|
+    /// | `i32`, `f64`, `bool` | `int`, `double`, `boolean` | `false` |
+    /// | `Option<i32>` | `Integer` | `false` (Option handles null) |
+    /// | `String` | `String` | `true` |
+    /// | `Vec<T>` | `List<T>` | `true` |
+    /// | `HashMap<K,V>` | `Map<K,V>` | `true` |
+    /// | User struct | Java object | `true` |
+    ///
+    /// # Default Implementation
+    ///
+    /// Returns `false` for all types. Override for types that correspond to reference types in other languages.
+    ///
+    /// # Examples
+    ///
+    /// ```rust,ignore
+    /// // String should be treated as reference type in Java
+    /// impl Serializer for String {
+    ///     fn fory_is_xlang_ref_type() -> bool {
+    ///         true
+    ///     }
+    /// }
+    ///
+    /// // i32 is primitive in Java (int)
+    /// impl Serializer for i32 {
+    ///     fn fory_is_xlang_ref_type() -> bool {
+    ///         false  // default
+    ///     }
+    /// }
+    /// ```
+    ///
+    /// # Implementation Notes
+    ///
+    /// - Only affects behavior when `context.is_xlang()` is true
+    /// - Used in [`fory_write`] to determine RefFlag behavior
+    /// - Fory implements this for all built-in types
+    /// - User types should override this for proper xlang interop
+    ///
+    /// [`fory_write`]: Serializer::fory_write
+    #[inline(always)]
+    fn fory_is_xlang_ref_type() -> bool
+    where
+        Self: Sized,
+    {
+        false
+    }
+
     /// **[USER IMPLEMENTATION REQUIRED]** Downcast to `&dyn Any` for dynamic type checking.
     ///
     /// This method enables runtime type checking and downcasting, required for

rust/fory-core/src/serializer/list.rs

@@ -121,6 +121,14 @@ impl<T: Serializer + ForyDefault> Serializer for Vec<T> {
     fn as_any(&self) -> &dyn std::any::Any {
         self
     }
+
+    fn fory_is_xlang_ref_type() -> bool
+    where
+        Self: Sized,
+    {
+        // Vec<T> corresponds to Java List<T>, which is a reference type
+        true
+    }
 }
 
 impl<T> ForyDefault for Vec<T> {
@@ -173,6 +181,14 @@ impl<T: Serializer + ForyDefault> Serializer for VecDeque<T> {
     fn as_any(&self) -> &dyn std::any::Any {
         self
     }
+
+    fn fory_is_xlang_ref_type() -> bool
+    where
+        Self: Sized,
+    {
+        // VecDeque<T> corresponds to Java List<T>, which is a reference type
+        true
+    }
 }
 
 impl<T> ForyDefault for VecDeque<T> {
@@ -225,6 +241,14 @@ impl<T: Serializer + ForyDefault> Serializer for LinkedList<T> {
     fn as_any(&self) -> &dyn std::any::Any {
         self
     }
+
+    fn fory_is_xlang_ref_type() -> bool
+    where
+        Self: Sized,
+    {
+        // LinkedList<T> corresponds to Java List<T>, which is a reference type
+        true
+    }
 }
 
 impl<T> ForyDefault for LinkedList<T> {

rust/fory-core/src/serializer/map.rs

@@ -638,6 +638,14 @@ impl<K: Serializer + ForyDefault + Eq + std::hash::Hash, V: Serializer + ForyDef
     fn fory_read_type_info(context: &mut ReadContext) -> Result<(), Error> {
         read_basic_type_info::<Self>(context)
     }
+
+    fn fory_is_xlang_ref_type() -> bool
+    where
+        Self: Sized,
+    {
+        // HashMap<K,V> corresponds to Java Map<K,V>, which is a reference type
+        true
+    }
 }
 
 impl<K, V> ForyDefault for HashMap<K, V> {
@@ -766,6 +774,14 @@ impl<K: Serializer + ForyDefault + Ord + std::hash::Hash, V: Serializer + ForyDe
     fn fory_read_type_info(context: &mut ReadContext) -> Result<(), Error> {
         read_basic_type_info::<Self>(context)
     }
+
+    fn fory_is_xlang_ref_type() -> bool
+    where
+        Self: Sized,
+    {
+        // BTreeMap<K,V> corresponds to Java Map<K,V>, which is a reference type
+        true
+    }
 }
 
 impl<K, V> ForyDefault for BTreeMap<K, V> {

rust/fory-core/src/serializer/set.rs

@@ -68,6 +68,14 @@ impl<T: Serializer + ForyDefault + Eq + std::hash::Hash> Serializer for HashSet<
     fn as_any(&self) -> &dyn std::any::Any {
         self
     }
+
+    fn fory_is_xlang_ref_type() -> bool
+    where
+        Self: Sized,
+    {
+        // HashSet<T> corresponds to Java Set<T>, which is a reference type
+        true
+    }
 }
 
 impl<T> ForyDefault for HashSet<T> {
@@ -115,6 +123,14 @@ impl<T: Serializer + ForyDefault + Ord> Serializer for BTreeSet<T> {
     fn as_any(&self) -> &dyn std::any::Any {
         self
     }
+
+    fn fory_is_xlang_ref_type() -> bool
+    where
+        Self: Sized,
+    {
+        // BTreeSet<T> corresponds to Java Set<T>, which is a reference type
+        true
+    }
 }
 
 impl<T> ForyDefault for BTreeSet<T> {

rust/fory-core/src/serializer/string.rs

@@ -98,6 +98,15 @@ impl Serializer for String {
     fn fory_read_type_info(context: &mut ReadContext) -> Result<(), Error> {
         read_basic_type_info::<Self>(context)
     }
+
+    #[inline(always)]
+    fn fory_is_xlang_ref_type() -> bool
+    where
+        Self: Sized,
+    {
+        // String is a reference type in Java, should write RefFlag in xlang mode
+        true
+    }
 }
 
 impl ForyDefault for String {

rust/tests/tests/test_cross_language.rs

@@ -734,3 +734,71 @@ fn test_struct_version_check() {
     assert_eq!(new_local_obj, local_obj);
     fs::write(&data_file_path, new_bytes).unwrap();
 }
+
+/// Test reference type alignment between Java and Rust in xlang mode.
+/// 
+/// This test verifies that:
+/// 1. Primitive types (i32, f64, bool) don't write RefFlag
+/// 2. Reference types (String, Vec, HashMap) write RefFlag in xlang mode
+/// 3. Java-serialized data can be correctly deserialized in Rust
+/// 4. Rust-serialized data can be correctly deserialized in Java
+#[test]
+#[ignore]
+fn test_reference_alignment() {
+    let data_file_path = get_data_file();
+    
+    // Read data serialized by Java
+    let bytes = fs::read(&data_file_path).unwrap();
+    let mut fory = Fory::default().xlang(true).compatible(true);
+    
+    let reader = Reader::new(bytes.as_slice());
+    let mut context = ReadContext::new_from_fory(reader, &fory);
+    
+    // Deserialize values in the same order as Java wrote them
+    // 1. Primitive int (no RefFlag)
+    let v1: i32 = fory.deserialize_with_context(&mut context).unwrap();
+    assert_eq!(v1, 42, "i32 value mismatch");
+    
+    // 2. Boxed Integer (with RefFlag for null handling)
+    let v2: Option<i32> = fory.deserialize_with_context(&mut context).unwrap();
+    assert_eq!(v2, Some(100), "Option<i32> value mismatch");
+    
+    // 3. String (reference type, with RefFlag)
+    let v3: String = fory.deserialize_with_context(&mut context).unwrap();
+    assert_eq!(v3, "hello", "String value mismatch");
+    
+    // 4. List<String> (reference type, with RefFlag)
+    let v4: Vec<String> = fory.deserialize_with_context(&mut context).unwrap();
+    assert_eq!(v4, vec!["a".to_string(), "b".to_string()], "Vec<String> value mismatch");
+    
+    // 5. Map<String, Integer> (reference type, with RefFlag)
+    let v5: HashMap<String, i32> = fory.deserialize_with_context(&mut context).unwrap();
+    let mut expected_map = HashMap::new();
+    expected_map.insert("key1".to_string(), 10);
+    expected_map.insert("key2".to_string(), 20);
+    assert_eq!(v5, expected_map, "HashMap value mismatch");
+    
+    // 6. Double (primitive, no RefFlag)
+    let v6: f64 = fory.deserialize_with_context(&mut context).unwrap();
+    assert_eq!(v6, 3.14, "f64 value mismatch");
+    
+    // 7. Boolean (primitive, no RefFlag)
+    let v7: bool = fory.deserialize_with_context(&mut context).unwrap();
+    assert_eq!(v7, true, "bool value mismatch");
+    
+    // Now serialize data back to Java
+    let writer = Writer::default();
+    let mut context = WriteContext::new_from_fory(writer, &fory);
+    
+    // Serialize in the same order
+    fory.serialize_with_context(&42i32, &mut context).unwrap();
+    fory.serialize_with_context(&Some(100i32), &mut context).unwrap();
+    fory.serialize_with_context(&"hello".to_string(), &mut context).unwrap();
+    fory.serialize_with_context(&vec!["a".to_string(), "b".to_string()], &mut context).unwrap();
+    fory.serialize_with_context(&expected_map, &mut context).unwrap();
+    fory.serialize_with_context(&3.14f64, &mut context).unwrap();
+    fory.serialize_with_context(&true, &mut context).unwrap();
+    
+    // Write back to file for Java to verify
+    fs::write(&data_file_path, context.writer.dump()).unwrap();
+}