#####What is jprotobuf#####
A very useful utility library for java programmer using google protobuf
jprotobuf是针对Java程序开发一套简易类库,目的是简化java语言对protobuf类库的使用
使用jprotobuf可以无需再去了解proto文件操作与语法,直接使用java注解定义字段类型即可。
#####How it works#####
jprotobuf工作原理如下:
- 扫描类上的注解的信息,进行分析(与protobuf读取proto文件进行分析过程相似)
- 根据注解分析的结果,动态生成java代码进行protobuf序列化与反序列化的功能实现
- 使用JDK6及以上的 code compile API进行编译后加载到classloader
#####Performace#####
jprotobuf 主要性能消耗在 扫描类上注解,动态生成代码编译的过程。
在执行序列化与反序列化的过程中,几乎与protobuf生成的代码效率等同。
#####Features#####
- 无需编写proto文件及繁琐的手工编译过程,支持基于POJO对象的注解方式,方便快捷。
支持protobuf所有类型,包括对象嵌套,数组,枚举类型 - 提供根据proto文件,动态生成代理对象,可省去POJO对象的编写工作。
完整支持proto文件所有功能,包括内联对象,匿名对象,枚举类型 - 提供从POJO对象的注解方式自动生成proto文件的功能, 方便 proto的管理与维护
#####关联项目:#####
JProtobuf-rpc-socket 基于socket的高性能RPC实现
访问地址: https://github.com/Baidu-ecom/Jprotobuf-rpc-socket
JProtobuf-rpc-http 基于JProtobuf的RPC实现,支持直接从IDL定义脚本发布RPC服务
访问地址: https://github.com/jhunters/JProtobuf-rpc-http
JDK 6 或以上版本
<dependency>
<groupId>com.baidu</groupId>
<artifactId>jprotobuf</artifactId>
<version>1.7.3</version>
</dependency>
示例:假如需要定义protobuf定义一个数据接口,包含两个属性,一个是string,一个是int32
a 定义.proto说明文件. test.proto
package pkg;
option java_package = "com.baidu.bjf.remoting.protobuf";
//这里声明输出的java的类名
option java_outer_classname = "SimpleTypeTest";
message InterClassName {
required string name = 1;
required int32 value = 2;
}
b 使用protoc.exe 编译.proto文件
protoc --java_out=src test.proto
c 编译生成的Java文件,利用protobuf API进行序列化与反序化操作
序列化操作:
InterClassName icn = InterClassName.newBuilder().setName("abc")
.setValue(100).build();
byte[] bb = icn.toByteArray();
反序化操作
byte[] bb = ...;
InterClassName icn = InterClassName.parseFrom(bb);
a 使用注解直接使用pojo对象
import com.baidu.bjf.remoting.protobuf.FieldType;
import com.baidu.bjf.remoting.protobuf.annotation.Protobuf;
/**
* A simple jprotobuf pojo class just for demo.
*
* @author xiemalin
* @since 1.0.0
*/
public class SimpleTypeTest {
@Protobuf(fieldType = FieldType.STRING, order = 1, required = true)
private String name;
@Protobuf(fieldType = FieldType.INT32, order = 2, required = false)
private int value;
public int getValue() {
return value;
}
public void setValue(int value) {
this.value = value;
}
}
b 使用jprotobuf API进行序列化与反序列化操作
Codec<SimpleTypeTest> simpleTypeCodec = ProtobufProxy
.create(SimpleTypeTest.class);
SimpleTypeTest stt = new SimpleTypeTest();
stt.name = "abc";
stt.setValue(100);
try {
// 序列化
byte[] bb = simpleTypeCodec.encode(stt);
// 反序列化
SimpleTypeTest newStt = simpleTypeCodec.decode(bb);
} catch (IOException e) {
e.printStackTrace();
}
public class AddressBookProtosPOJO {
@Protobuf(fieldType = FieldType.OBJECT, order=1, required = false)
public Person person;
@Protobuf(fieldType = FieldType.OBJECT, order=2, required = false)
public List<Person> person;
}
public class Person {
@Protobuf(fieldType = FieldType.STRING, order=1, required = true)
public String name;
@Protobuf(fieldType = FieldType.INT32, order=2, required = true)
public int id;
@Protobuf(fieldType = FieldType.STRING, order=3, required = false)
public String email;
@Protobuf(fieldType = FieldType.DOUBLE, order=4, required = false)
public Double doubleF;
@Protobuf(fieldType = FieldType.FLOAT, order=5, required = false)
public Float floatF;
@Protobuf(fieldType = FieldType.BYTES, order=6, required = false)
public byte[] bytesF;
@Protobuf(fieldType=FieldType.BOOL, order=7, required=false)
public Boolean boolF;
}
JProtobuf提供一个非常实用的功能,可以动态生成Protobuf的IDL描述文件内容
//返回的内容即为 Protobuf的IDL描述文件
String code = ProtobufIDLGenerator.getIDL(SimpleTypeTest.class);
public class SimpleTypeTest {
@Protobuf(fieldType = FieldType.STRING, order = 1, required = true)
private String name;
@Protobuf(fieldType = FieldType.INT32, order = 2, required = false)
private int value;
public int getValue() {
return value;
}
public void setValue(int value) {
this.value = value;
}
}
JProtobuf提供一个更简单的功能,可支持动态Protobuf对象的生成功能,省去了注释的使用 基本使用示例如下:
@Test
public void testDecode() throws Exception {
// 通过 .proto描述文件生成动态解析对象
String protoCotent = "package mypackage.test; " +
"option java_package = \"com.baidu.bjf.remoting.protobuf.simplestring\";" +
"option java_outer_classname = \"StringTypeClass\"; " +
"message StringMessage { " +
" required string message = 1; }" ;
IDLProxyObject object = ProtobufIDLProxy.createSingle(protoCotent);
//if .proto IDL defines multiple messages use as follow
//Map<String, IDLProxyObject> objects = ProtobufIDLProxy.create(protoCotent);
// 动态设置字段值
object.put("message", "hello你好");
//propogation object set
//object.put("sub.field", "hello world");
// protobuf 序列化
byte[] bb = object.encode();
// protobuf 反序列化
IDLProxyObject result = object.decode(bb);
Assert.assertEquals("hello你好", result.get("message"));
//propogation object get
//result.get("sub.field")
}
该功能可以更方便的设置对象属性的类型定义
public class AddressBookProtosPOJOWithDefault {
@Protobuf
public PersonPOJOWithDefault list;
@Protobuf
public String name;
}
上面的代码等同于如下设置
public class AddressBookProtosPOJOWithDefault {
@Protobuf(fieldType = FieldType.OBJECT, order=1, required = false)
public PersonPOJO list;
@Protobuf(fieldType = FieldType.STRING, order=2, required = false)
public String name;
}
public class EnumPOJOClass {
@Protobuf(fieldType = FieldType.ENUM)
public EnumAttrPOJO enumAttr;
}
使用枚举类型必须注意,如果枚举类型的值不是使用默认的ordinal的方式,则必须实现EnumReadable接口,示例代码如下:
public enum EnumAttrPOJO implements EnumReadable {
STRING(100), INT(50);
private final int value;
EnumAttrPOJO(int value) { this.value = value; }
public int toValue() { return this.value; }
/* (non-Javadoc)
* @see com.baidu.bjf.remoting.protobuf.Enumable#value()
*/
public int value() {
return toValue();
}
}
使用示例:
ProtobufProxy.create(AddressBookProtosPOJO.class, false, new File("D:/"));
ProtobufIDLProxy.create(string, false, new File("D:/"));
上面的示例,则会直接把生成的中间子节码文件生成到D盘根据目录下。
注:目前ProtobufIDLProxy已经能完全支持含有内部类或内部枚举类型的message的动态解析。
更多使用示例请参见testcase代码。
email: rigel-opensource@baidu.com