Google Protocol Buffer 3 : Web Service Example

google-protocol-buffer-201115

0. Get The Code!

Protocol Buffer Sample : You can download the source code of this tutorial from the following link : https://github.com/letsprog/learning-protobuf3

1. What is Google Protocol Buffer?

Google Protocol Buffer is a Serialization library for structured data. An object serialization can be for storing data or for exchanging data between applications. These applications can be of different languages, for example one app can be coded in Java and the other in C++. So this library grants interoperability between many languages.

Google Protocol Buffer uses an Interface Definition Language to define the data structure, and it offers a compiler to generate source from description. Such description is often put in a file with .proto as an extension, but is just a convention and not mandatory. Every structure is defined as a message, which can have many fields. All the fields are implicitly considered as optional.

Serializing an object would give a stream of bytes, which can be deserialized (parsed) by Google Protocol Buffer to restore the initial object.

There are major differences between Protobuf v2 and v3. For example, in Protobuf v3, a field can no longer be declared as optional nor required, and the default keyword is no longer allowed.

The official documentation of Google is very interesting and is worth reading : https://developers.google.com/protocol-buffers/

2. How to integrate Google Protocol Buffer library in a Java project?

If you are using Maven, all what you need is to include this dependency :

To get the most recent version, you check for the releases in maven repository.

Remark : For this tutorial we are using Google Protocol Buffer 3.

3. How does using Interface Definition Language sound like in Google Protocol Buffer?

All what you have to do is to define your structures as messages in the definition file, and precising the syntax to use, whether “proto3” for Protocol Buffer version 3, or “proto2” for version 2.

4. How to generate code source from the definition file (.proto) ?

First, download the binary version which fits most your OS and platform :

Then, execute the binary protoc. For example, for generating Java code source in the Windows binary version :

5. Practical Use Case : Exchange a Protocol Buffer stream via Web Service

We will create 3 projects :

  • learning-protobuf3-model-generator : Maven project to automate generating Java classes code source files and packaging them as .class files in a JAR file.
  • learning-protobuf3-ws-service : Maven project to show how to produce a Protocol Buffer stream.
  • learning-protobuf3-ws-client : Maven project to show how to consume a Protocol Buffer stream.

5.1. Model Generator

5.1.1. Project structure

Protocol Buffer Model Generator Project Structure

5.1.2. Definition file : universe.proto

Let’s suppose that we want to a create a model for a Galaxy :

  • A galaxy can have any number of stars.
  • Each star can have many planets.
  • A planet can be either rocky either gaseous.
  • A planet can have many moons.

Protocol Buffer : Case of Study

As we intend to exchange the serialized Protobuf data between programs (client and server) we can consider it as a Data Transfer Project. That is why I have chosen the generated classes to be placed in the package “com.letsprog.learning.protobuf3.dto”.

5.1.3. Batch file to generate code source : universe.proto

Remark : As you notice from the batch file, this file requires 4 arguments. These arguments will be set at pom.xml level as we will see next.

5.1.4. pom.xml

5.1.5. Including generated code source in Build Path

Compile project and Add target\generated as Source Folder. This will make your Eclipse IDE shut up .

Protocol Buffer (Protobuf) : Generated Sources added to Build Path.

5.1.6. How to construct an object whose class is generated by Protocol Buffer ?

Protocol Buffer library doesn’t generate only the classes but also the builders which makes constructing an object so much easy.

However, only builders are allowed for constructing the object. This means the generated classes are immutables, and using mutators is not possible.

Here it is a dummy factory to construct our Miky Way Galaxy . You can run this class as it has a static main method which calls the accessors of the constructed DTO to display data.

5.2. Web Service producing a Protobuf Stream

5.2.1. pom.xml

5.2.2. JAX-RS Activator

5.2.3. Web Service Method

5.2.3. Web Service Deployment

Deploy the archive learning-protobuf3-ws-service.war into your favorite Application Server, for example WildFly 9. You can keep the port to the default value : 8080. Verify that that the war was deployed successfuly.

5.3. WS Client consuming a Protobuf Stream

5.3.1. pom.xml

5.3.2. WS Client using Jersey implementation

5.3.3. Testing client

Run the client as it defines a static main method. These text should be displayed on your console :