Implementation:Ray project Ray ObjectSerializer

Knowledge Sources	Ray
Domains	Distributed_Computing, Java_Runtime
Last Updated	2026-02-13 16:00 GMT

Overview

Serialization gateway for all objects entering and leaving the Ray object store, implementing the cross-language serialization protocol and error type mapping.

Description

ObjectSerializer serializes Java objects to NativeRayObject instances and deserializes them back, handling metadata-driven type dispatch. During serialization, it chooses the appropriate metadata tag (JAVA, XLANG, RAW, ACTOR_HANDLE, TASK_EXECUTION_EXCEPTION) based on the object type and delegates to the Serializer for encoding. During deserialization, it inspects the metadata prefix to determine the object type and either deserializes normally, wraps data as a RayException, or reconstructs an actor handle. Thread-local state tracks contained object IDs and outer object context for nested object references.

Usage

Use ObjectSerializer whenever objects need to be stored in or retrieved from the Ray object store. It is called by TaskExecutor to serialize task results and by the object store to deserialize fetched objects. It enables interoperability between Java, Python, and C++ through the cross-language metadata protocol.

Code Reference

Source Location

• Repository: Ray
• File: java/runtime/src/main/java/io/ray/runtime/object/ObjectSerializer.java

Signature

public class ObjectSerializer {

  public static final byte[] OBJECT_METADATA_TYPE_CROSS_LANGUAGE;
  public static final byte[] OBJECT_METADATA_TYPE_JAVA;
  public static final byte[] OBJECT_METADATA_TYPE_PYTHON;
  public static final byte[] OBJECT_METADATA_TYPE_RAW;
  public static final byte[] OBJECT_METADATA_TYPE_ACTOR_HANDLE;

  public static Object deserialize(
      NativeRayObject nativeRayObject,
      ObjectId objectId,
      Class<?> objectType) { ... }

  public static NativeRayObject serialize(Object object) { ... }

  static void addContainedObjectId(ObjectId objectId) { ... }
  static void setOuterObjectId(ObjectId objectId) { ... }
  static ObjectId getOuterObjectId() { ... }
  static void resetOuterObjectId() { ... }
}

Import

import io.ray.runtime.object.ObjectSerializer;

I/O Contract

Input (deserialize)

Parameter	Type	Description
nativeRayObject	NativeRayObject	The serialized object containing data bytes and metadata bytes
objectId	ObjectId	The associated object ID (used for error reporting and actor ID extraction)
objectType	Class<?>	Expected Java type for deserialization

Input (serialize)

Parameter	Type	Description
object	Object	Java object to serialize; may be a byte[], ByteBuffer, RayTaskException, NativeActorHandle, or any serializable object

Output

Method	Return Type	Description
deserialize	Object	Deserialized Java object, or a RayException subclass if the metadata indicates an error
serialize	NativeRayObject	Serialized representation with appropriate metadata tag for the object type

Metadata Types

Constant	Value	Description
OBJECT_METADATA_TYPE_JAVA	"JAVA"	Java-only serialized object
OBJECT_METADATA_TYPE_CROSS_LANGUAGE	"XLANG"	Cross-language compatible serialized object
OBJECT_METADATA_TYPE_RAW	"RAW"	Raw byte array or ByteBuffer
OBJECT_METADATA_TYPE_PYTHON	"PYTHON"	Python-serialized object (cannot deserialize in Java)
OBJECT_METADATA_TYPE_ACTOR_HANDLE	"ACTOR_HANDLE"	Serialized actor handle

Usage Examples

// Serialize a Java object for the object store
NativeRayObject serialized = ObjectSerializer.serialize("hello world");
// serialized.metadata == OBJECT_METADATA_TYPE_CROSS_LANGUAGE or OBJECT_METADATA_TYPE_JAVA

// Serialize raw bytes (cross-language compatible)
NativeRayObject rawSerialized = ObjectSerializer.serialize(new byte[]{1, 2, 3});
// rawSerialized.metadata == OBJECT_METADATA_TYPE_RAW

// Deserialize an object from the store
Object result = ObjectSerializer.deserialize(nativeRayObject, objectId, String.class);

// Serialize a task exception
RayTaskException exception = new RayTaskException("task failed");
NativeRayObject errorSerialized = ObjectSerializer.serialize(exception);
// errorSerialized.metadata == TASK_EXECUTION_EXCEPTION_META

Related Pages

• Environment:Ray_project_Ray_Java_Build_Environment