or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

buffer-management.mdgraph-processing.mdindex.mdinput-output-streams.mdserialization-utilities.md
tile.json

serialization-utilities.mddocs/

Serialization Utilities

The serialization utilities provide high-level interfaces for converting Java objects to/from byte arrays and streams. These are the primary entry points for most serialization tasks.

ProtostuffIOUtil

Main utility class for serializing objects using the Protostuff format, which is optimized for performance and provides some enhancements over standard Protocol Buffer encoding.

Serialization Methods

public static <T> byte[] toByteArray(T message, Schema<T> schema, LinkedBuffer buffer)

Serializes a message to a byte array using the Protostuff format.

Parameters:

  • message - The object to serialize
  • schema - The schema defining the message structure
  • buffer - LinkedBuffer for memory management

Returns: Byte array containing the serialized data

Usage Example:

LinkedBuffer buffer = LinkedBuffer.allocate(LinkedBuffer.DEFAULT_BUFFER_SIZE);
byte[] data = ProtostuffIOUtil.toByteArray(person, personSchema, buffer);
public static <T> void writeTo(OutputStream out, T message, Schema<T> schema, LinkedBuffer buffer) throws IOException

Writes a serialized message directly to an OutputStream.

public static <T> void writeTo(DataOutput out, T message, Schema<T> schema, LinkedBuffer buffer) throws IOException

Writes a serialized message to a DataOutput.

public static <T> void writeDelimitedTo(OutputStream out, T message, Schema<T> schema, LinkedBuffer buffer) throws IOException

Writes a length-delimited message to an OutputStream, prefixing the data with its length.

Deserialization Methods

public static <T> void mergeFrom(byte[] data, T message, Schema<T> schema) throws IOException

Deserializes data from a byte array into an existing message object.

Parameters:

  • data - Byte array containing serialized data
  • message - Target object to populate (must be pre-instantiated)
  • schema - Schema defining the message structure
public static <T> void mergeFrom(byte[] data, int offset, int length, T message, Schema<T> schema) throws IOException

Deserializes data from a specific portion of a byte array.

public static <T> void mergeFrom(InputStream in, T message, Schema<T> schema) throws IOException

Deserializes data from an InputStream.

public static <T> void mergeFrom(DataInput in, T message, Schema<T> schema) throws IOException

Deserializes data from a DataInput.

Collection Utilities

public static <T> List<T> parseListFrom(InputStream in, Schema<T> schema) throws IOException

Parses a list of messages from an InputStream, where each message is length-delimited.

Pipe Creation

public static Pipe newPipe(byte[] data)

Creates a protostuff pipe from a byte array for efficient data transfer operations.

public static Pipe newPipe(byte[] data, int offset, int len)

Creates a protostuff pipe from a specific portion of a byte array.

public static Pipe newPipe(InputStream in)

Creates a protostuff pipe from an InputStream.

ProtobufIOUtil

Utility class for serializing objects using the standard Protocol Buffer format, ensuring compatibility with other protobuf implementations.

API Methods

ProtobufIOUtil provides the same method signatures as ProtostuffIOUtil but uses Protocol Buffer encoding:

public static <T> byte[] toByteArray(T message, Schema<T> schema, LinkedBuffer buffer)
public static <T> void writeTo(OutputStream out, T message, Schema<T> schema, LinkedBuffer buffer) throws IOException
public static <T> void writeTo(CodedOutput output, T message, Schema<T> schema, LinkedBuffer buffer) throws IOException
public static <T> void writeDelimitedTo(OutputStream out, T message, Schema<T> schema, LinkedBuffer buffer) throws IOException
public static <T> void mergeFrom(byte[] data, T message, Schema<T> schema) throws IOException
public static <T> void mergeFrom(byte[] data, int offset, int length, T message, Schema<T> schema) throws IOException
public static <T> void mergeFrom(InputStream in, T message, Schema<T> schema) throws IOException
public static <T> void mergeFrom(CodedInput input, T message, Schema<T> schema) throws IOException
public static <T> List<T> parseListFrom(InputStream in, Schema<T> schema) throws IOException
public static Pipe newPipe(byte[] data)
public static Pipe newPipe(byte[] data, int offset, int len)
public static Pipe newPipe(InputStream in)

Format Differences

The key differences between ProtostuffIOUtil and ProtobufIOUtil:

  • ProtostuffIOUtil: Uses optimized Protostuff format with better performance for nested messages and certain data types
  • ProtobufIOUtil: Uses standard Protocol Buffer wire format, ensuring compatibility with protobuf implementations in other languages

Usage Examples

// Standard protobuf serialization
LinkedBuffer buffer = LinkedBuffer.allocate(LinkedBuffer.DEFAULT_BUFFER_SIZE);
byte[] protobufData = ProtobufIOUtil.toByteArray(message, schema, buffer);

// Deserialize protobuf data
Message deserializedMessage = schema.newMessage();
ProtobufIOUtil.mergeFrom(protobufData, deserializedMessage, schema);

// Write to stream with length delimiter
ProtobufIOUtil.writeDelimitedTo(outputStream, message, schema, buffer);

// Parse multiple messages from stream
List<Message> messages = ProtobufIOUtil.parseListFrom(inputStream, schema);

Error Handling

Both utility classes throw:

  • IOException for I/O related errors
  • ProtobufException for protocol-level errors (malformed data, invalid encoding)
  • RuntimeException for truncated or corrupted data

Performance Considerations

  • Reuse LinkedBuffer instances when possible to minimize memory allocations
  • Use stream-based methods for large data sets to avoid loading everything into memory
  • Choose ProtostuffIOUtil for better performance in pure Java environments
  • Choose ProtobufIOUtil when interoperability with other protobuf implementations is required