Recent Posts

Sunday, 7 August 2016

Google Protocol Buffers Example



Defining Your Protocol Format
package com.ashok;

option java_package = "com.ashok.protobuf";
option java_outer_classname = "AddressBookProtos";

message Person {
  required string name = 1;
  required int32 id = 2;
  optional string email = 3;

  enum PhoneType {
    MOBILE = 0;
    HOME = 1;
    WORK = 2;
  }

  message PhoneNumber {
    required string number = 1;
    optional PhoneType type = 2 [default = HOME];
  }

  repeated PhoneNumber phone = 4;
}

message AddressBook {
  repeated Person person = 1;
}
     The .proto file starts with a package declaration, which helps to prevent naming conflicts between different projects.

     After the package declaration, you can see two options that are Java-specific: java_package and java_outer_classname. java_package specifies in what Java package name your generated classes should live. If you don't specify this explicitly, it simply matches the package name given by the package declaration, but these names usually aren't appropriate Java package names (since they usually don't start with a domain name). The java_outer_classname option defines the class name which should contain all of the classes in this file. If you don't give a java_outer_classname explicitly, it will be generated by converting the file name to camel case. For example, "my_proto.proto" would, by default, use "MyProto" as the outer class name.

     Next, you have your message definitions. A message is just an aggregate containing a set of typed fields. Many standard simple data types are available as field types, including bool, int32, float, double, and string. You can also add further structure to your messages by using other message types as field types – in the above example the Person message contains PhoneNumber messages, while the AddressBook message contains Person messages. You can even define message types nested inside other messages – as you can see, the PhoneNumber type is defined inside Person. You can also define enum types if you want one of your fields to have one of a predefined list of values – here you want to specify that a phone number can be one of MOBILE, HOME, or WORK.

Compiling Your Protocol Buffers
     Google provides a compiler called protoc which can produce output for C++, Java or Python. Now run the compiler, specifying the source directory (where your application's source code lives – the current directory is used if you don't provide a value), the destination directory (where you want the generated code to go; often the same as $SRC_DIR), and the path to your .proto. In this case, you...:
protoc -I=$SRC_DIR --java_out=$DST_DIR $SRC_DIR/addressbook.proto
     Because you want Java classes, you use the --java_out option – similar options are provided for other supported languages.

   This generates com/ashok/protobuf/AddressBookProtos.java in your specified destination directory.

     Let's look at some of the generated code and see what classes and methods the compiler has created for you. If you look in AddressBookProtos.java, you can see that it defines a class called AddressBookProtos, nested within which is a class for each message you specified in addressbook.proto. Each class has its own Builder class that you use to create instances of that class.

     Both messages and builders have auto-generated accessor methods for each field of the message; messages have only getters while builders have both getters and setters. Here are some of the accessors for the Person class.
// required string name = 1;
public boolean hasName();
public String getName();

// required int32 id = 2;
public boolean hasId();
public int getId();

// optional string email = 3;
public boolean hasEmail();
public String getEmail();

// repeated .tutorial.Person.PhoneNumber phone = 4;
public List<PhoneNumber> getPhoneList();
public int getPhoneCount();
public PhoneNumber getPhone(int index);
     Where as Person.Builder has the same getters plus setters
// required string name = 1;
public boolean hasName();
public java.lang.String getName();
public Builder setName(String value);
public Builder clearName();

// required int32 id = 2;
public boolean hasId();
public int getId();
public Builder setId(int value);
public Builder clearId();

// optional string email = 3;
public boolean hasEmail();
public String getEmail();
public Builder setEmail(String value);
public Builder clearEmail();

// repeated .tutorial.Person.PhoneNumber phone = 4;
public List<PhoneNumber> getPhoneList();
public int getPhoneCount();
public PhoneNumber getPhone(int index);
public Builder setPhone(int index, PhoneNumber value);
public Builder addPhone(PhoneNumber value);
public Builder addAllPhone(Iterable<PhoneNumber> value);
public Builder clearPhone();
     As you can see, there are simple JavaBeans-style getters and setters for each field. There are also has getters for each singular field which return true if that field has been set. Finally, each field has a clear method that un-sets the field back to its empty state.

     Repeated fields have some extra methods – a Count method (which is just shorthand for the list's size), getters and setters which get or set a specific element of the list by index, an add method which appends a new element to the list, and an addAll method which adds an entire container full of elements to the list.

Builders vs. Messages

     The message classes generated by the protocol buffer compiler are all immutable. Once a message object is constructed, it cannot be modified, just like a Java String. To construct a message, you must first construct a builder, set any fields you want to set to your chosen values, then call the builder's build() method.

     You may have noticed that each method of the builder which modifies the message returns another builder. The returned object is actually the same builder on which you called the method. It is returned for convenience so that you can string several setters together on a single line of code.

     Here's an example of how you would create an instance of Person.
Person ashok =
  Person.newBuilder()
    .setId(123)
    .setName("Ashok Kumar")
    .setEmail("ashokkumar.mariyala@gmail.com")
    .addPhone(
      Person.PhoneNumber.newBuilder()
        .setNumber("+91-9000027370")
        .setType(Person.PhoneType.MOBILE))
    .build();
Standard Message Methods
     Each message and builder class also contains a number of other methods that let you check or manipulate the entire message, including:

isInitialized()
     Checks if all the required fields have been set.

toString()
     Returns a human-readable representation of the message, particularly useful for debugging.

mergeFrom(Message other) (builder only)
     Merges the contents of other into this message, overwriting singular fields and concatenating repeated ones.

clear() (builder only) 
     Clears all the fields back to the empty state.

     These methods implement the Message and Message.Builder interfaces shared by all Java messages and builders. For more information, see the complete API documentation for Message.

Parsing and Serialization
     Finally, each protocol buffer class has methods for writing and reading messages of your chosen type using the protocol buffer binary format. These include:

byte[] toByteArray();
     Serializes the message and returns a byte array containing its raw bytes.

static Person parseFrom(byte[] data);
     Parses a message from the given byte array.

void writeTo(OutputStream output);
     Serializes the message and writes it to an OutputStream.

static Person parseFrom(InputStream input);
     Reads and parses a message from an InputStream

Writing a message
package com.ashok.protobuf;

import com.ashok.protobuf.AddressBookProtos.AddressBook;
import com.ashok.protobuf.AddressBookProtos.Person;
import java.io.BufferedReader;
import java.io.FileInputStream;
import java.io.FileNotFoundException;
import java.io.FileOutputStream;
import java.io.InputStreamReader;
import java.io.IOException;
import java.io.PrintStream;

class AddPerson {
   static Person PromptForAddress(BufferedReader stdin, PrintStream stdout) throws IOException {
      Person.Builder person = Person.newBuilder();

      stdout.print("Enter person ID: ");
      person.setId(Integer.valueOf(stdin.readLine()));

      stdout.print("Enter name: ");
      person.setName(stdin.readLine());

      stdout.print("Enter email address (blank for none): ");
      String email = stdin.readLine();
      if (email.length() > 0) {
         person.setEmail(email);
      }

      while (true) {
         stdout.print("Enter a phone number (or leave blank to finish): ");
         String number = stdin.readLine();
         if (number.length() == 0) {
            break;
         }

         Person.PhoneNumber.Builder phoneNumber = Person.PhoneNumber.newBuilder().setNumber(number);

         stdout.print("Is this a mobile, home, or work phone? ");
         String type = stdin.readLine();
         if (type.equals("mobile")) {
            phoneNumber.setType(Person.PhoneType.MOBILE);
         } else if (type.equals("home")) {
            phoneNumber.setType(Person.PhoneType.HOME);
         } else if (type.equals("work")) {
            phoneNumber.setType(Person.PhoneType.WORK);
         } else {
            stdout.println("Unknown phone type.  Using default.");
         }
         person.addPhone(phoneNumber);
      }
      return person.build();
   }

   public static void main(String[] args) throws Exception {
      if (args.length != 1) {
         System.err.println("Usage:  AddPerson ADDRESS_BOOK_FILE");
         System.exit(-1);
      }

      AddressBook.Builder addressBook = AddressBook.newBuilder();

      try {
         addressBook.mergeFrom(new FileInputStream(args[0]));
      } catch (FileNotFoundException e) {
         System.out.println(args[0] + ": File not found.  Creating a new file.");
      }

      addressBook.addPerson(PromptForAddress(new BufferedReader(
            new InputStreamReader(System.in)), System.out));

      FileOutputStream output = new FileOutputStream(args[0]);
      addressBook.build().writeTo(output);
      output.close();
   }
}
Reading a message
package com.ashok.protobuf;

import com.ashok.protobuf.AddressBookProtos.AddressBook;
import com.ashok.protobuf.AddressBookProtos.Person;
import java.io.FileInputStream;

class ListPeople {
   static void Print(AddressBook addressBook) {
      for (Person person : addressBook.getPersonList()) {
         System.out.println("Person ID: " + person.getId());
         System.out.println("  Name: " + person.getName());
         if (person.hasEmail()) {
            System.out.println("  E-mail address: " + person.getEmail());
         }

         for (Person.PhoneNumber phoneNumber : person.getPhoneList()) {
            switch (phoneNumber.getType()) {
            case MOBILE:
               System.out.print("  Mobile phone #: ");
               break;
            case HOME:
               System.out.print("  Home phone #: ");
               break;
            case WORK:
               System.out.print("  Work phone #: ");
               break;
            }
            System.out.println(phoneNumber.getNumber());
         }
      }
   }

   public static void main(String[] args) throws Exception {
      if (args.length != 1) {
         System.err.println("Usage:  ListPeople ADDRESS_BOOK_FILE");
         System.exit(-1);
      }
      AddressBook addressBook = AddressBook.parseFrom(new FileInputStream(args[0]));
      Print(addressBook);
   }
}

     That's it guys. This is all about Google Protocol Buffers Tutorial. Let me know your comments and suggestions about this tutorial. Thank you.

No comments:

Post a Comment