or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

durations.mdfield-mask.mdindex.mdjson-format.mdstructured-data.mdtimestamps.md
tile.json

tessl/maven-com-google-protobuf--protobuf-java-util

Utilities for Protocol Buffers including JSON format conversion, field mask operations, time-based utilities, and structured data manipulation.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
mavenpkg:maven/com.google.protobuf/protobuf-java-util@4.31.x

To install, run

npx @tessl/cli install tessl/maven-com-google-protobuf--protobuf-java-util@4.31.0

index.mddocs/

protobuf-java-util

A comprehensive set of utilities for working with Protocol Buffers in Java applications. The library provides essential functionality for JSON format conversion, field mask operations, time-based utilities, structured data manipulation, and proto file operations. All utilities are designed for maximum reusability across protobuf-based systems including web APIs, data processing pipelines, and distributed systems.

Package Information

  • Package Name: protobuf-java-util
  • Package Type: maven
  • Language: Java
  • Installation: Add to pom.xml: 
    <dependency>
  <groupId>com.google.protobuf</groupId>
  <artifactId>protobuf-java-util</artifactId>
  <version>4.31.1</version>
</dependency>

Core Imports

import com.google.protobuf.util.JsonFormat;
import com.google.protobuf.util.FieldMaskUtil;
import com.google.protobuf.util.Timestamps;
import com.google.protobuf.util.Durations;
import com.google.protobuf.util.Structs;
import com.google.protobuf.util.Values;
import com.google.protobuf.util.ProtoFileUtil;

Basic Usage

import com.google.protobuf.util.JsonFormat;
import com.google.protobuf.util.Timestamps;
import com.google.protobuf.util.Durations;
import com.google.protobuf.Timestamp;
import com.google.protobuf.Duration;

// JSON format conversion
JsonFormat.Printer printer = JsonFormat.printer();
JsonFormat.Parser parser = JsonFormat.parser();

// Create and print a message as JSON
String jsonString = printer.print(myMessage);

// Parse JSON back to protobuf message
MyMessage.Builder messageBuilder = MyMessage.newBuilder();
parser.merge(jsonString, messageBuilder);
MyMessage parsedMessage = messageBuilder.build();

// Timestamp utilities
Timestamp now = Timestamps.now();
Timestamp fromEpoch = Timestamps.fromMillis(System.currentTimeMillis());
String timestampString = Timestamps.toString(now);

// Duration utilities
Duration oneHour = Durations.fromHours(1);
Duration fiveMinutes = Durations.fromMinutes(5);
Duration total = Durations.add(oneHour, fiveMinutes);

// Proto file utilities
String editionString = ProtoFileUtil.getEditionString(Edition.EDITION_2023);

Architecture

The protobuf-java-util library is organized around several key functional areas:

  • JSON Format Conversion: Bidirectional conversion between protobuf messages and JSON using Proto3 JSON mapping specification
  • Field Mask Operations: Utilities for selective field operations, merging, and filtering using FieldMask proto type
  • Time Utilities: Comprehensive timestamp and duration manipulation supporting RFC 3339 format and various time unit conversions
  • Structured Data: Builder utilities for creating google.protobuf.Struct and google.protobuf.Value messages
  • Proto File Utilities: Helper functions for working with proto file metadata and descriptors

Capabilities

JSON Format Conversion

Complete bidirectional conversion system between protobuf messages and JSON format, supporting Proto3 JSON mapping specification with configurable options for field naming, default values, and type registries.

public static JsonFormat.Printer printer();
public static JsonFormat.Parser parser();

// Printer methods
public JsonFormat.Printer usingTypeRegistry(TypeRegistry registry);
public JsonFormat.Printer includingDefaultValueFields(Set<FieldDescriptor> fields);
public JsonFormat.Printer preservingProtoFieldNames();
public JsonFormat.Printer omittingInsignificantWhitespace();
public String print(MessageOrBuilder message) throws InvalidProtocolBufferException;

// Parser methods  
public JsonFormat.Parser usingTypeRegistry(TypeRegistry registry);
public JsonFormat.Parser ignoringUnknownFields();
public void merge(String json, Message.Builder builder) throws InvalidProtocolBufferException;

JSON Format Conversion

Field Mask Operations

Comprehensive utilities for working with FieldMask protobuf type, enabling selective field operations, merging strategies, validation, and set operations on field paths.

public static FieldMask fromString(String value);
public static FieldMask fromStringList(Class<? extends Message> type, Iterable<String> paths);
public static String toJsonString(FieldMask fieldMask);
public static boolean isValid(Class<? extends Message> type, FieldMask fieldMask);
public static FieldMask union(FieldMask firstMask, FieldMask secondMask, FieldMask... otherMasks);
public static void merge(FieldMask mask, Message source, Message.Builder destination);

Field Mask Operations

Timestamp Utilities

Complete timestamp manipulation supporting RFC 3339 format, various time unit conversions, validation, comparison, and arithmetic operations with full range checking and normalization.

public static final Timestamp MIN_VALUE;
public static final Timestamp MAX_VALUE; 
public static final Timestamp EPOCH;

public static Timestamp now();
public static Timestamp fromMillis(long milliseconds);
public static Timestamp parse(String value) throws ParseException;
public static String toString(Timestamp timestamp);
public static boolean isValid(Timestamp timestamp);
public static Duration between(Timestamp from, Timestamp to);
public static Timestamp add(Timestamp start, Duration length);

Timestamp Utilities

Duration Utilities

Duration manipulation with support for various time units, string format conversion, validation, comparison, and arithmetic operations with proper normalization and range checking.

public static final Duration MIN_VALUE;
public static final Duration MAX_VALUE;
public static final Duration ZERO;

public static Duration fromHours(long hours);
public static Duration fromMinutes(long minutes);
public static Duration fromSeconds(long seconds);
public static Duration parse(String value) throws ParseException;
public static String toString(Duration duration);
public static boolean isValid(Duration duration);
public static Duration add(Duration d1, Duration d2);
public static Duration subtract(Duration d1, Duration d2);

Duration Utilities

Structured Data Utilities

Factory methods for creating google.protobuf.Struct and google.protobuf.Value messages with type-safe builders for various data types including null, boolean, number, string, struct, and list values.

// Structs utilities
public static Struct of(String k1, Value v1);
public static Struct of(String k1, Value v1, String k2, Value v2);
public static Struct of(String k1, Value v1, String k2, Value v2, String k3, Value v3);

// Values utilities
public static Value ofNull();
public static Value of(boolean value);
public static Value of(double value);
public static Value of(String value);
public static Value of(Struct value);
public static Value of(ListValue value);

Structured Data Utilities

Proto File Utilities

Utility functions for working with proto file metadata and descriptors, particularly for handling protobuf edition information.

public static String getEditionString(Edition edition);

Types

// Field Mask Merge Options
public static final class FieldMaskUtil.MergeOptions {
  public boolean replaceMessageFields();
  public boolean replaceRepeatedFields(); 
  public boolean replacePrimitiveFields();
  public FieldMaskUtil.MergeOptions setReplaceMessageFields(boolean value);
  public FieldMaskUtil.MergeOptions setReplaceRepeatedFields(boolean value);
  public FieldMaskUtil.MergeOptions setReplacePrimitiveFields(boolean value);
}

// JSON Format Type Registry
public static class JsonFormat.TypeRegistry {
  public static TypeRegistry getEmptyTypeRegistry();
  public static TypeRegistry.Builder newBuilder();
  public Descriptor find(String name);
  
  public static class Builder {
    public Builder add(Descriptor messageType);
    public Builder add(Iterable<Descriptor> messageTypes);
    public TypeRegistry build();
  }
}