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

index.mddocs/

Protostuff Core

Protostuff Core is a high-performance Java serialization library that provides efficient Protocol Buffer-compatible serialization for Java objects. It offers both protobuf-compatible format and protostuff's own optimized format, with support for object graphs, cyclic dependencies, and forward/backward compatibility for schema evolution.

This documentation covers both the core serialization implementations (protostuff-core module) and the foundational APIs they depend on (protostuff-api module).

Package Information

  • Package Name: protostuff-core
  • Package Type: maven
  • Group ID: io.protostuff
  • Language: Java
  • Installation: Add to your Maven pom.xml: 
    <dependency>
  <groupId>io.protostuff</groupId>
  <artifactId>protostuff-core</artifactId>
  <version>1.8.0</version>
</dependency>

Core Imports

// Core serialization utilities (protostuff-core)
import io.protostuff.ProtostuffIOUtil;
import io.protostuff.ProtobufIOUtil;
import io.protostuff.GraphIOUtil;

// Foundational APIs (protostuff-api, included as dependency)
import io.protostuff.Schema;
import io.protostuff.LinkedBuffer;
import io.protostuff.Input;
import io.protostuff.Output;

Basic Usage

import io.protostuff.*;

// Example message class with schema
public class Person {
    String name;
    int age;
    String email;
    
    // Constructors, getters, setters...
}

// Serialize using Protostuff format
LinkedBuffer buffer = LinkedBuffer.allocate(LinkedBuffer.DEFAULT_BUFFER_SIZE);
byte[] data = ProtostuffIOUtil.toByteArray(person, schema, buffer);

// Deserialize using Protostuff format  
Person deserializedPerson = schema.newMessage();
ProtostuffIOUtil.mergeFrom(data, deserializedPerson, schema);

// Or use Protocol Buffer format
byte[] protobufData = ProtobufIOUtil.toByteArray(person, schema, buffer);
Person protobufPerson = schema.newMessage();
ProtobufIOUtil.mergeFrom(protobufData, protobufPerson, schema);

Architecture

Protostuff Core is built around several key components:

  • Serialization Utilities: Main entry points (ProtostuffIOUtil, ProtobufIOUtil, GraphIOUtil) providing high-level serialization/deserialization operations
  • Input/Output System: Low-level streaming classes for reading and writing data in various formats
  • Buffer Management: Efficient memory management through linked buffer structures to minimize allocations
  • Graph Processing: Support for object references and cyclic dependencies through specialized graph-aware serializers
  • Format Compatibility: Both native Protostuff format (optimized) and Protocol Buffer format (interoperable) support

Capabilities

Serialization Utilities

High-level utilities for common serialization tasks including byte array conversion, stream I/O, and message merging. The primary entry points for most applications.

// Protostuff format utilities
public final class ProtostuffIOUtil {
    // Serialization
    public static <T> byte[] toByteArray(T message, Schema<T> schema, LinkedBuffer buffer);
    public static <T> int writeTo(OutputStream out, T message, Schema<T> schema, LinkedBuffer buffer);
    public static <T> int writeDelimitedTo(OutputStream out, T message, Schema<T> schema, LinkedBuffer buffer);
    public static <T> int writeListTo(OutputStream out, List<T> messages, Schema<T> schema, LinkedBuffer buffer);
    
    // Deserialization
    public static <T> void mergeFrom(byte[] data, T message, Schema<T> schema);
    public static <T> void mergeFrom(byte[] data, int offset, int length, T message, Schema<T> schema);
    public static <T> void mergeFrom(InputStream in, T message, Schema<T> schema);
    public static <T> int mergeDelimitedFrom(InputStream in, T message, Schema<T> schema);
    public static <T> List<T> parseListFrom(InputStream in, Schema<T> schema);
}

// Protocol Buffer format utilities  
public final class ProtobufIOUtil {
    public static <T> byte[] toByteArray(T message, Schema<T> schema, LinkedBuffer buffer);
    public static <T> void mergeFrom(byte[] data, T message, Schema<T> schema);
    public static <T> int writeTo(OutputStream out, T message, Schema<T> schema, LinkedBuffer buffer);
}

Serialization Utilities

Input and Output Streams

Low-level streaming interfaces for reading and writing protobuf-encoded data from various sources including byte arrays, ByteBuffers, and InputStreams.

public abstract class CodedInput {
    public abstract int readRawByte() throws IOException;
    public abstract String readString() throws IOException;
    public abstract int readTag() throws IOException;
    public abstract boolean isAtEnd() throws IOException;
}

public final class ProtobufOutput implements Output {
    public ProtobufOutput(LinkedBuffer buffer);
    public void writeString(int fieldNumber, CharSequence value, boolean repeated) throws IOException;
    public void writeInt32(int fieldNumber, int value, boolean repeated) throws IOException;
}

Input and Output Streams

Graph Processing

Specialized serialization for object graphs containing references and cyclic dependencies, which standard protocol buffers cannot handle natively.

public final class GraphIOUtil {
    // Serialization
    public static <T> byte[] toByteArray(T message, Schema<T> schema, LinkedBuffer buffer);
    public static <T> int writeTo(OutputStream out, T message, Schema<T> schema, LinkedBuffer buffer);
    public static <T> int writeDelimitedTo(OutputStream out, T message, Schema<T> schema, LinkedBuffer buffer);
    
    // Deserialization  
    public static <T> void mergeFrom(byte[] data, T message, Schema<T> schema);
    public static <T> void mergeFrom(byte[] data, int offset, int length, T message, Schema<T> schema);
    public static <T> void mergeFrom(InputStream in, T message, Schema<T> schema);
    public static <T> int mergeDelimitedFrom(InputStream in, T message, Schema<T> schema);
}

Graph Processing

Buffer Management

Efficient memory management through linked buffer structures that minimize memory allocations and provide reusable buffer pools.

public final class LinkedBuffer {
    public static final int MIN_BUFFER_SIZE = 256;
    public static final int DEFAULT_BUFFER_SIZE = 512;
    
    // Allocation methods
    public static LinkedBuffer allocate();
    public static LinkedBuffer allocate(int size);
    public static LinkedBuffer allocate(int size, LinkedBuffer previous);
    public static LinkedBuffer wrap(byte[] array, int offset, int length);
    public static LinkedBuffer use(byte[] buffer);
    
    // Utility methods
    public static int writeTo(OutputStream out, LinkedBuffer node) throws IOException;
    public LinkedBuffer clear();
}

Buffer Management

Advanced Input/Output Classes

Specialized input and output implementations for different data sources and memory optimization scenarios.

public final class ByteBufferInput extends CodedInput;
public final class ProtostuffOutput implements Output;
public final class LowCopyProtostuffOutput implements Output;
public final class LowCopyProtobufOutput implements Output;

These classes provide optimized implementations for specific use cases like ByteBuffer sources and memory-efficient output operations.

Exception Handling

public class ProtobufException extends ProtostuffException {
    public ProtobufException(String description);
    public ProtobufException(String description, Throwable cause);
}

Protostuff Core throws ProtobufException for protocol-level errors such as malformed data, invalid tags, or truncated messages. I/O related errors are propagated as standard IOException.