/jackson-datatype-protobuf

Primary LanguageJavaApache License 2.0Apache-2.0

Overview

Jackson module that adds support for serializing and deserializing Google's Protocol Buffers to and from JSON.

Usage

Maven dependency

To use module on Maven-based projects, use following dependency:

<dependency>
  <groupId>com.hubspot.jackson</groupId>
  <artifactId>jackson-datatype-protobuf</artifactId>
  <version><!-- see table below --></version>
</dependency>

Versions

Starting with version 0.9.12, only Jackson 2.9+ is supported. If you're using Jackson 2.9 or newer, you can use the latest version of this library in Maven Central (link).

If you're using a version of Jackson prior to 2.9, you can use the last release before support was dropped:

Jackson 2.7.x Jackson 2.8.x
0.9.11-jackson2.7 0.9.11-jackson2.8

Registering module

Registration is done as follows:

ObjectMapper mapper = new ObjectMapper();
mapper.registerModule(new ProtobufModule());

after which functionality is available for all normal Jackson operations.

Interop with Protobuf 3 Canonical JSON Representation

Protobuf 3 specifies a canonical JSON representation (available here). This library conforms to that representation with a few exceptions:

  • unsigned numbers (uint32, fixed32, uint64, fixed64) can be improperly serialized as negative numbers. This can be overridden by enabling ProtobufJacksonConfig#properUnsignedNumberSerialization
  • int64, fixed64, uint64 are written as JSON numbers instead of strings. This can be overridden by enabling ProtobufJacksonConfig#serializeLongsAsString
  • Any objects don't have any special handling, so the value will be a base64 string, and the type URL field name is typeUrl instead of @type
  • original field names are not accepted on deserialization. This can be overriden by enabling ProtobufJacksonConfig#acceptLiteralFieldnames

If you want interop with canonical serialization/deserialization, you can call ProtobufJacksonConfig#useCanonicalSerialization. This will enable all of the available options to get as close to the canonical behavior as possible. The behavior of this method may change in the future as new options are added.

Protobuf 2 Support

Support has been dropped for com.google.protobuf:protobuf-java:2.x, but you can use an older release if necessary:

  • 0.9.10-jackson2.9-proto2
  • 0.9.10-jackson2.8-proto2
  • 0.9.10-jackson2.7-proto2
  • 0.9.10-preJackson2.7-proto2

Gotchas

This library assumes that field names in proto files will be lowercase with underscores, as is recommended by the protobuf style guide: https://developers.google.com/protocol-buffers/docs/style#message-and-field-names

Use underscore_separated_names for field names – for example, song_name.

If your field names don't match this convention, you may need to set a PropertyNamingStrategy on your ObjectMapper for things to work as expected. For example, if your proto field names are camel case, you could configure your ObjectMapper to use PropertyNamingStrategy.LOWER_CAMEL_CASE.