tessl/maven-io-protostuff--protostuff-core

Core serialization library and APIs for protostuff providing efficient Protocol Buffer-compatible serialization with schema evolution support

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Protostuff Core

Name: tessl/maven-io-protostuff--protostuff-core
Author: tessl

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.

Workspace: tessl
Visibility: Public
Created: 6 months ago
Last updated: about 2 months ago
Describes: pkg:maven/io.protostuff/protostuff-core@1.8.x
Publish Source: CLI
Badge