Protocol buffers are a flexible, efficient, automated mechanism for serializing structured data
Define how you want your data to be structured
Use special generated source code to easily write and read structured data to and from a variety of data streams .
Data serializing format defining protocol buffer in .proto file
protocol buffer is small logical record & contain key-val pair and a uniquely number :
a example is following
package tutorial;
option java_package = "com.example.tutorial";
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;
}
Once defined .proto format file and could user proto compiler to generate java classes
ProtoBuf Data Type:
Protocol Buffers fields as one of following:
required
: a well-formed message must have exactly one of this field.
optional
: a well-formed message can have zero or one of this field (but not more than one).repeated
: this field can be repeated any number of times (including zero) in a well-formed message.
Comments should use C-style //
syntax.
Compiler generates a .java source file , special Builder Class to Create Message Instance
Code Style :
Use CamelCase for message names
Use underscore_separated_names for field names
Use CamelCase for enum type names and CAPITALS_WITH_UNDERSCORES for value names
use CamelCase for both the service name and any RPC method names
Protocol Buffers Compiler Command
protobuf protoc --help
Usage: protoc [OPTION] PROTO_FILES
Parse PROTO_FILES and generate output based on the options given:
-IPATH, --proto_path=PATH Specify the directory in which to search for
imports. May be specified multiple times;
directories will be searched in order. If not
given, the current working directory is used.
--version Show version info and exit.
-h, --help Show this text and exit.
--encode=MESSAGE_TYPE Read a text-format message of the given type
from standard input and write it in binary
to standard output. The message type must
be defined in PROTO_FILES or their imports.
--decode=MESSAGE_TYPE Read a binary message of the given type from
standard input and write it in text format
to standard output. The message type must
be defined in PROTO_FILES or their imports.
--decode_raw Read an arbitrary protocol message from
standard input and write the raw tag/value
pairs in text format to standard output. No
PROTO_FILES should be given when using this
flag.
-oFILE, Writes a FileDescriptorSet (a protocol buffer,
--descriptor_set_out=FILE defined in descriptor.proto) containing all of
the input files to FILE.
--include_imports When using --descriptor_set_out, also include
all dependencies of the input files in the
set, so that the set is self-contained.
--include_source_info When using --descriptor_set_out, do not strip
SourceCodeInfo from the FileDescriptorProto.
This results in vastly larger descriptors that
include information about the original
location of each decl in the source file as
well as surrounding comments.
--error_format=FORMAT Set the format in which to print errors.
FORMAT may be 'gcc' (the default) or 'msvs'
(Microsoft Visual Studio format).
--plugin=EXECUTABLE Specifies a plugin executable to use.
Normally, protoc searches the PATH for
plugins, but you may specify additional
executables not in the path using this flag.
Additionally, EXECUTABLE may be of the form
NAME=PATH, in which case the given plugin name
is mapped to the given executable even if
the executable's own name differs.
--cpp_out=OUT_DIR Generate C++ header and source.
--java_out=OUT_DIR Generate Java source file.
--python_out=OUT_DIR Generate Python source file.
Java Code Example:
package com.example.tutorial;
import com.example.tutorial.AddressBookProtos.AddressBook;
import com.example.tutorial.AddressBookProtos.Person;
import com.example.tutorial.AddressBookProtos.Person.PhoneNumber;
import com.example.tutorial.AddressBookProtos.Person.PhoneType;
public class Examples {
public static void main(String[] args) {
AddressBook.Builder addressBookBuilder = AddressBook.newBuilder();
Person.Builder personBuilder = Person.newBuilder();
PhoneNumber.Builder phoneBuilder = PhoneNumber.newBuilder();
phoneBuilder.setNumber("13728369472");
phoneBuilder.setType(PhoneType.WORK);
personBuilder.setName("darion");
personBuilder.setId(0);
personBuilder.setEmail("darion.yaphet@gmail.com");
personBuilder.setPhone(0, phoneBuilder);
addressBookBuilder.setPerson(0, personBuilder);
}
}
Java RPC Service Examples:
Protocol Buffer as Following :
package echo;
message EchoRequest
{
required string message = 1;
};
message EchoResponse
{
required string response = 1;
};
service EchoService
{
rpc Echo(EchoRequest) returns (EchoResponse);
};
参考文献:
https://developers.google.com/protocol-buffers/