Skip to main content

Protobuf Text Format Basics

Juneau supports converting arbitrary POJOs to and from the Protobuf Text Format using native serializers and parsers implemented without any external dependencies. This is the human-readable text format (not the binary wire format) used for protobuf configuration files, debugging, and interop with tools like protoc --decode. The PrototextSerializer converts POJOs directly to Protobuf Text Format, and the PrototextParser creates POJOs directly from protobuf text without intermediate DOM objects.

No .proto schema files are required—Java bean metadata provides the type information.

Protobuf Text Format support is included in juneau-marshall.

Maven
<dependency>
    <groupId>org.apache.juneau</groupId>
    <artifactId>juneau-marshall</artifactId>
    <version>${juneau.version}</version>
</dependency>

Quick Start​

// Serialize a bean to Protobuf Text Format
Person p = new Person("Alice", 30);
String proto = Prototext.of(p);

Produces:

name: "Alice"
age: 30

Parsing​

// Parse Protobuf Text Format into a bean
Person parsed = Prototext.to(proto, Person.class);

// Parse into a Map or JsonMap
JsonMap map = Prototext.to(proto, JsonMap.class);

Serialization​

// Use the default serializer
String proto = PrototextSerializer.DEFAULT.write(someObject);

// Use the marshaller for convenience
String proto = Prototext.of(someObject);

Bean-to-Protobuf Mapping​

The conversion follows the Protobuf Text Format specification:

  • Maps and beans → Message fields with brace delimiters or colon syntax
  • Collections and arrays of simple values → List syntax [v1, v2, ...]
  • Collections of beans → Repeated field names
  • Strings → Quoted strings with C-style escaping
  • Numbers → Numeric literals (decimal, hex, octal)
  • Booleans → true / false
  • Enums → Unquoted identifiers
  • Date/time and Duration → ISO 8601 strings
  • null → Omitted (no null representation in protobuf text format)

Pre-configured instances​

InstanceDescription
PrototextSerializer.DEFAULTDefault settings.
PrototextSerializer.DEFAULT_READABLESame, with useWhitespace() enabled for more readable output.
PrototextParser.DEFAULTDefault parser.

Serializer settings​

Configured through PrototextSerializer.create() (see PrototextSerializer.Builder), in addition to the settings inherited from WriterSerializer (useWhitespace(), addBeanTypes(), keepNullProperties(), swaps, etc.).

Builder methodDefaultDescription
useListSyntaxForBeans(boolean)falseWrite collections of beans using list syntax ([{...}, {...}]) instead of repeated field names.
useColonForMessages(boolean)falseWrite message-valued fields as field: { ... } instead of field { ... }.
PrototextSerializer s = PrototextSerializer.create()
    .useListSyntaxForBeans(true)
    .useColonForMessages(true)
    .build();
String proto = s.write(someBean);

Parser settings​

PrototextParser has no format-specific settings beyond those inherited from ReaderParser (see PrototextParser.Builder). Comments (# ...) in the input are ignored.

Annotations​

The @Prototext annotation (on a class, field or method) has a comment attribute. When specified, a # text comment line is written before the field:

public class Person {
    @Prototext(comment="Years since birth")
    public int age = 30;

    public String name = "Alice";
}

Produces:

# Years since birth
age: 30
name: "Alice"

@PrototextConfig applies serializer settings on a REST class or method (see Context Annotations):

AttributeDescription
useListSyntaxForBeans"true" / "false" (default). Maps to useListSyntaxForBeans(boolean).
useColonForMessages"true" / "false" (default). Maps to useColonForMessages(boolean).
rankOrdering relative to other config annotations.
@Rest
@PrototextConfig(useColonForMessages="true")
public class MyResource extends BasicRestServlet { ... }

Media Types​

  • Produces: text/protobuf
  • Accept: text/protobuf, text/x-protobuf

REST Integration​

// Use BasicPrototextConfig for Protobuf-only REST resources
@Rest
public class MyResource extends RestServlet implements BasicPrototextConfig { ... }

// Protobuf is also included in BasicUniversalConfig
@Rest
public class MyResource extends RestServlet implements BasicUniversalConfig { ... }
See Also