Optional binary messages ais
4 stars based on
This tutorial provides a basic Java programmer's introduction to working with protocol buffers. By walking through creating a simple example application, it shows you how to Define message formats in a. Optional binary messages aisheys the protocol buffer compiler.
Use the Java protocol buffer API to write and read messages. This isn't a comprehensive guide to using protocol buffers in Java. Why Use Protocol Buffers?
The example we're going to use is a very simple "address book" application that can read and write people's contact details to and from a file. Each person in the address book has a name, an ID, an email address, and a contact phone number. How do you serialize and retrieve structured data like this? There are a few ways to solve this problem: This is the default approach since it's built into the language, but it has a host of well-known problems see Effective Optional binary messages aisheys, by Josh Bloch pp.
You can invent an ad-hoc way to encode the data items into a single string — such as encoding 4 ints as " This is a simple and flexible approach, although it does require writing one-off encoding and parsing code, and the parsing imposes a small run-time cost.
This works best for encoding very simple data. Serialize the data to XML. This approach can be very attractive since XML is sort of human readable and there are binding libraries for lots of languages. Also, navigating an XML DOM tree is considerably more complicated than navigating simple fields in a class normally would be.
Optional binary messages aisheys buffers are the flexible, efficient, automated solution to solve exactly this problem. With protocol buffers, you write a. From that, the protocol buffer compiler creates a class that implements automatic encoding and parsing of the protocol buffer data with an efficient binary format.
The generated class provides getters and setters for the fields that make up a protocol buffer and takes care of the details of reading and writing the protocol buffer as a unit. Importantly, the protocol buffer format supports the idea of extending the format over time in such a way that the code can still read data encoded with the old format.
The example code is included in the source code package, under the "examples" directory. Defining Your Protocol Format To create your address book application, you'll need to start with a. The definitions in a. Let's go optional binary messages aisheys each part of the file and see what it does. After the package declaration, you can see two options that are Java-specific: 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.
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 boolint32floatdoubleand 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 optional binary messages aisheys is defined inside Person. Tag numbers require one less byte to encode than higher numbers, so as an optimization you can decide to use those tags for the commonly used or repeated elements, leaving tags 16 and higher for less-commonly used optional elements. Each element in a repeated field requires re-encoding the tag number, so repeated fields are particularly good candidates for this optimization.
Each field must be annotated with one of the following modifiers: Trying to build an uninitialized message will throw a RuntimeException. Parsing an uninitialized message will throw an IOException. Other than this, a required field behaves exactly like an optional field. If an optional field value isn't set, a default value is used.
For simple types, you can specify your own default value, as we've done for the phone number type in the example. Otherwise, a system default is used: For embedded messages, the default value is always the "default instance" or "prototype" of the message, which has none of its fields set.
Calling the accessor to get optional binary messages aisheys value of an optional or required field which has not been explicitly set always returns that field's default value.
The order of the repeated values will be preserved in the protocol buffer. Think of repeated fields as dynamically sized arrays. Required Is Forever You should be very careful about marking fields as required. If at some point you wish to stop writing or sending a required field, it will be problematic to change the field to an optional field — old readers will consider messages without this field to be incomplete and may reject or drop them unintentionally.
You should consider writing application-specific custom validation routines for your buffers instead. Some engineers at Google have come to the conclusion that using required does more harm than good; they prefer to use only optional and repeated. However, this view is not universal. You'll find a complete guide to writing. Don't go looking for facilities similar optional binary messages aisheys class inheritance, though — protocol optional binary messages aisheys don't do that.
Compiling Your Protocol Buffers Now that you have a. To do this, you need to run the protocol buffer compiler protoc on your. In this case, you The Protocol Buffer API Let's look at some optional binary messages aisheys the generated code and see what classes and methods the compiler has created for you.
If you look in AddressBookProtos. Each class has its own Builder class that you use to create instances of that class. You can find out more about builders in the Builders vs. 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 implementations omitted for brevity: Builder has the same optional binary messages aisheys plus setters: There are also optional binary messages aisheys 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 sizegetters 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.
Notice how these optional binary messages aisheys methods use camel-case naming, even though the. This transformation is done automatically by the protocol buffer compiler so that the generated classes match standard Java style conventions. You should always use lowercase-with-underscores for field names in your. See the style guide for more on good. For more information on exactly what members the protocol compiler generates for any particular field definition, see the Java generated code reference.
PhoneNumber is generated, as you'd expect, as optional binary messages aisheys nested class within Person. 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 optional binary messages aisheys 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: 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 are just a couple of the options provided for parsing and serialization. Again, see the Message API reference for a complete list. Protocol Buffers and O-O Design Protocol buffer classes are basically dumb data holders like structs in C ; they don't make good first class citizens in an object model.
If you want to add richer behaviour to a generated class, the best way to do this is to wrap the generated protocol buffer class in an application-specific class.
Wrapping protocol buffers is also a good idea if you don't have control over the design of the. In that case, you can use the wrapper class to craft an interface better suited to the unique environment of your application: You should never add behaviour to the generated classes by inheriting from optional binary messages aisheys. This will break internal mechanisms and is not good object-oriented practice anyway. Writing A Message Now let's try using your protocol buffer classes.
The optional binary messages aisheys thing you want your address book application to be able to do is write personal details to your address book file. To do this, you need to create and populate instances of your protocol buffer classes and then write them to an output stream. Here is a program which reads an AddressBook from a file, adds one new Person to it based on user input, and writes the new AddressBook back out to the file again.
The parts which directly call or reference code generated by the protocol compiler are highlighted. AddressBook ; import com. Person ; import java. Creating a new optional binary messages aisheys.