Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/infinispan/protostream

ProtoStream is a serialization library based on Protocol Buffers
https://github.com/infinispan/protostream

infinispan java protobuf serialization-library

Last synced: 2 days ago
JSON representation

ProtoStream is a serialization library based on Protocol Buffers

Awesome Lists containing this project

README 

        
# ![ProtoStream](./infinispan_protostream_stacked.png)



![Maven Central Version](https://img.shields.io/maven-central/v/org.infinispan.protostream/protostream?versionPrefix=5&style=for-the-badge)

![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/infinispan/protostream/test_report.yaml?branch=main&style=for-the-badge)

[![License](https://img.shields.io/github/license/infinispan/infinispan?style=for-the-badge&logo=apache)](https://www.apache.org/licenses/LICENSE-2.0)

![Supported JVM Versions](https://img.shields.io/badge/JVM-17-green.svg?style=for-the-badge&logo=openjdk)

[![Javadoc](https://img.shields.io/badge/Javadoc-online-green.svg?style=for-the-badge&logo=openjdk)](http://www.javadoc.io/doc/org.infinispan.protostream/protostream)

[![Project Chat](https://img.shields.io/badge/zulip-join_chat-pink.svg?style=for-the-badge&logo=zulip)](https://infinispan.zulipchat.com/)



ProtoStream is a Java serialization library based on the [Protocol Buffers](https://developers.google.com/protocol-buffers/) data format. 

It is open source software released under the [Apache License, v2.0](https://www.apache.org/licenses/LICENSE-2.0 "The Apache License, v2.0").

ProtoStream is part of the [Infinispan](https://github.com/infinispan/infinispan) platform, but can be used standalone.

For more information about Infinispan visit the project's website on [https://infinispan.org](https://infinispan.org "the Infinispan project page").

Documentation on how to use ProtoStream in your projects is available [https://infinispan.org/docs/stable/titles/encoding/encoding.html#marshalling_user_types](here).



Features

--------

* annotate your Java classes, enums and records to automatically generate the `.proto` schema

* provide adapters for third-party classes

* compile-time generation of high-performance protocol buffers serializers / deserializers

* Protocol Buffers 2 and 3

* support for custom annotations

* provides a library of ready-made adapters for common JDK classes (`BigDecimal`, `UUID`, `ArrayList`, `LocalDateTime` and more)

* programmatic `.proto` schema generation

* built-in backwards compatibility checks to ensure schemas use [https://protobuf.dev/programming-guides/dos-donts/](Protocol Buffers best practices)



Usage

-----



If you are using Maven, add this dependency to your `pom.xml` file:

   

```xml



   org.infinispan.protostream

   protostream

   5.0.12.Final



```



If you are using Gradle, add this dependency to your build file:



```

dependencies { 

    implementation 'org.infinispan.protostream:protostream:5.0.12.Final'

}

```



Annotation processor

--------------------



The Java compiler discovers annotation processors differently, depending on the version and the options in use.

With Java up to version 21, it's enough to put the `protostream-processor` dependency on the classpath and it 

will be automatically discovered by the service loader mechanism. Another way, which is mandatory since Java 22,

is to use the `--processor-path` option.



```shell

javac --processor-path /path/to/protostream-processor-5.0.5.Final.jar:... ...

```



Using Maven:

```xml



  maven-compiler-plugin

  3.13.0

  

    

    

      

        org.infinispan.protostream

        protostream-processor

        5.0.5.Final

      

    

  



```



Using Gradle:

```

dependencies {

    annotationProcessor 'org.infinispan.protostream:protostream-processor:5.0.5.Final'

    ...

}

```



The annotation processor supports some configuration options:



* `protostream.debug` prints out debug information during the processing phase.

* `protostream.fullyqualifiedannotations` when generating the `.proto` files, the annotation names are stripped of the package name. This flag keeps the fully-qualified annotation names in the generated files.



You can pass these arguments to `javac` using the `-Aoption=value` argument. 

The following `pom.xml` snippet shows how to do it with Maven:



```xml



  maven-compiler-plugin

  3.12.1

  

    

      -Aprotostream-debug=true

    

    

    

      

        org.infinispan.protostream

        protostream-processor

        5.0.5.Final

      

    

  



```



Requirements

------------



Target runtime platform is Java 17 or newer.



Requires Java 17 or newer to build.



Maven 3.6.0 or newer.



Bugs

----

Bug reports go [here](https://issues.jboss.org/projects/IPROTO)