|
|
|
|
@ -1,10 +1,14 @@ |
|
|
|
|
Protocol Buffers - Google's data interchange format |
|
|
|
|
=================================================== |
|
|
|
|
|
|
|
|
|
[](https://travis-ci.org/google/protobuf) |
|
|
|
|
|
|
|
|
|
Copyright 2008 Google Inc. |
|
|
|
|
|
|
|
|
|
This directory contains the Java Protocol Buffers Nano runtime library. |
|
|
|
|
|
|
|
|
|
Installation - With Maven |
|
|
|
|
========================= |
|
|
|
|
------------------------- |
|
|
|
|
|
|
|
|
|
The Protocol Buffers build is managed using Maven. If you would |
|
|
|
|
rather build without Maven, see below. |
|
|
|
|
@ -41,7 +45,7 @@ rather build without Maven, see below. |
|
|
|
|
The .jar will be placed in the "target" directory. |
|
|
|
|
|
|
|
|
|
Installation - Without Maven |
|
|
|
|
============================ |
|
|
|
|
---------------------------- |
|
|
|
|
|
|
|
|
|
If you would rather not install Maven to build the library, you may |
|
|
|
|
follow these instructions instead. Note that these instructions skip |
|
|
|
|
@ -66,7 +70,7 @@ running unit tests. |
|
|
|
|
4) Install the classes wherever you prefer. |
|
|
|
|
|
|
|
|
|
Nano version |
|
|
|
|
============================ |
|
|
|
|
------------ |
|
|
|
|
|
|
|
|
|
JavaNano is a special code generator and runtime library designed specially for |
|
|
|
|
resource-restricted systems, like Android. It is very resource-friendly in both |
|
|
|
|
@ -130,7 +134,9 @@ penalty. This is not a problem if the field has no default or is an |
|
|
|
|
empty default. |
|
|
|
|
|
|
|
|
|
Nano Generator options |
|
|
|
|
---------------------- |
|
|
|
|
|
|
|
|
|
``` |
|
|
|
|
java_package -> <file-name>|<package-name> |
|
|
|
|
java_outer_classname -> <file-name>|<package-name> |
|
|
|
|
java_multiple_files -> true or false |
|
|
|
|
@ -139,8 +145,10 @@ optional_field_style -> default or accessors |
|
|
|
|
enum_style -> c or java |
|
|
|
|
ignore_services -> true or false |
|
|
|
|
parcelable_messages -> true or false |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
**java_package=\<file-name\>|\<package-name\>** (no default) |
|
|
|
|
|
|
|
|
|
java_package=<file-name>|<package-name> (no default) |
|
|
|
|
This allows overriding the 'java_package' option value |
|
|
|
|
for the given file from the command line. Use multiple |
|
|
|
|
java_package options to override the option for multiple |
|
|
|
|
@ -149,7 +157,8 @@ java_package=<file-name>|<package-name> (no default) |
|
|
|
|
the same option defined in the file if present, or the |
|
|
|
|
proto package if present, or the default Java package. |
|
|
|
|
|
|
|
|
|
java_outer_classname=<file-name>|<outer-classname> (no default) |
|
|
|
|
**java_outer_classname=\<file-name\>|\<outer-classname\>** (no default) |
|
|
|
|
|
|
|
|
|
This allows overriding the 'java_outer_classname' option |
|
|
|
|
for the given file from the command line. Use multiple |
|
|
|
|
java_outer_classname options to override the option for |
|
|
|
|
@ -160,7 +169,8 @@ java_outer_classname=<file-name>|<outer-classname> (no default) |
|
|
|
|
outer class will nest all classes and integer constants |
|
|
|
|
generated from file-scope messages and enums. |
|
|
|
|
|
|
|
|
|
java_multiple_files={true,false} (no default) |
|
|
|
|
**java_multiple_files={true,false}** (no default) |
|
|
|
|
|
|
|
|
|
This allows overriding the 'java_multiple_files' option |
|
|
|
|
in all source files and their imported files from the |
|
|
|
|
command line. The final value of this option for each |
|
|
|
|
@ -178,10 +188,11 @@ java_multiple_files={true,false} (no default) |
|
|
|
|
incorrect references to the imported messages and enum |
|
|
|
|
constants. |
|
|
|
|
|
|
|
|
|
java_nano_generate_has={true,false} (default: false) |
|
|
|
|
**java_nano_generate_has={true,false}** (default: false) |
|
|
|
|
|
|
|
|
|
DEPRECATED. Use optional_field_style=accessors. |
|
|
|
|
|
|
|
|
|
If true, generates a public boolean variable has<fieldname> |
|
|
|
|
If true, generates a public boolean variable has\<fieldname\> |
|
|
|
|
accompanying each optional or required field (not present for |
|
|
|
|
repeated fields, groups or messages). It is set to false initially |
|
|
|
|
and upon clear(). If parseFrom(...) reads the field from the wire, |
|
|
|
|
@ -195,20 +206,21 @@ java_nano_generate_has={true,false} (default: false) |
|
|
|
|
many cases reading the default works and determining whether the |
|
|
|
|
field was received over the wire is irrelevant. |
|
|
|
|
|
|
|
|
|
optional_field_style={default,accessors,reftypes} (default: default) |
|
|
|
|
**optional_field_style={default,accessors,reftypes}** (default: default) |
|
|
|
|
|
|
|
|
|
Defines the style of the generated code for fields. |
|
|
|
|
|
|
|
|
|
* default * |
|
|
|
|
* default |
|
|
|
|
|
|
|
|
|
In the default style, optional fields translate into public mutable |
|
|
|
|
Java fields, and the serialization process is as discussed in the |
|
|
|
|
"IMPORTANT" section above. |
|
|
|
|
|
|
|
|
|
* accessors * |
|
|
|
|
* accessors |
|
|
|
|
|
|
|
|
|
When set to 'accessors', each optional field is encapsulated behind |
|
|
|
|
4 accessors, namely get<fieldname>(), set<fieldname>(), has<fieldname>() |
|
|
|
|
and clear<fieldname>() methods, with the standard semantics. The hazzer's |
|
|
|
|
4 accessors, namely get\<fieldname\>(), set\<fieldname\>(), has\<fieldname\>() |
|
|
|
|
and clear\<fieldname\>() methods, with the standard semantics. The hazzer's |
|
|
|
|
return value determines whether a field is serialized, so this style is |
|
|
|
|
useful when you need to serialize a field with the default value, or check |
|
|
|
|
if a field has been explicitly set to its default value from the wire. |
|
|
|
|
@ -224,7 +236,7 @@ optional_field_style={default,accessors,reftypes} (default: default) |
|
|
|
|
reducing the final code size. |
|
|
|
|
TODO(maxtroy): find ProGuard config that would work the best. |
|
|
|
|
|
|
|
|
|
* reftypes * |
|
|
|
|
* reftypes |
|
|
|
|
|
|
|
|
|
When set to 'reftypes', each proto field is generated as a public Java |
|
|
|
|
field. For primitive types, these fields use the Java reference types |
|
|
|
|
@ -254,10 +266,11 @@ optional_field_style={default,accessors,reftypes} (default: default) |
|
|
|
|
required field (you have no reason to), you can only use |
|
|
|
|
java_nano_generate_has=true. |
|
|
|
|
|
|
|
|
|
enum_style={c,java} (default: c) |
|
|
|
|
**enum_style={c,java}** (default: c) |
|
|
|
|
|
|
|
|
|
Defines where to put the int constants generated from enum members. |
|
|
|
|
|
|
|
|
|
* c * |
|
|
|
|
* c |
|
|
|
|
|
|
|
|
|
Use C-style, so the enum constants are available at the scope where |
|
|
|
|
the enum is defined. A file-scope enum's members are referenced like |
|
|
|
|
@ -265,7 +278,7 @@ enum_style={c,java} (default: c) |
|
|
|
|
referenced as 'Message.ENUM_VALUE'. The enum name is unavailable. |
|
|
|
|
This complies with the Micro code generator's behavior. |
|
|
|
|
|
|
|
|
|
* java * |
|
|
|
|
* java |
|
|
|
|
|
|
|
|
|
Use Java-style, so the enum constants are available under the enum |
|
|
|
|
name and referenced like 'EnumName.ENUM_VALUE' (they are still int |
|
|
|
|
@ -277,18 +290,21 @@ enum_style={c,java} (default: c) |
|
|
|
|
compiler inlines all referenced enum constants into the call sites, |
|
|
|
|
the interface remains unused and can be removed by ProGuard. |
|
|
|
|
|
|
|
|
|
ignore_services={true,false} (default: false) |
|
|
|
|
**ignore_services={true,false}** (default: false) |
|
|
|
|
|
|
|
|
|
Skips services definitions. |
|
|
|
|
|
|
|
|
|
Nano doesn't support services. By default, if a service is defined |
|
|
|
|
it will generate a compilation error. If this flag is set to true, |
|
|
|
|
services will be silently ignored, instead. |
|
|
|
|
|
|
|
|
|
parcelable_messages={true,false} (default: false) |
|
|
|
|
**parcelable_messages={true,false}** (default: false) |
|
|
|
|
|
|
|
|
|
Android-specific option to generate Parcelable messages. |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
To use nano protobufs within the Android repo: |
|
|
|
|
---------------------------------------------- |
|
|
|
|
|
|
|
|
|
- Set 'LOCAL_PROTOC_OPTIMIZE_TYPE := nano' in your local .mk file. |
|
|
|
|
When building a Java library or an app (package) target, the build |
|
|
|
|
@ -313,17 +329,20 @@ To use nano protobufs within the Android repo: |
|
|
|
|
the two above. |
|
|
|
|
|
|
|
|
|
To use nano protobufs outside of Android repo: |
|
|
|
|
---------------------------------------------- |
|
|
|
|
|
|
|
|
|
- Link with the generated jar file |
|
|
|
|
<protobuf-root>java/target/protobuf-java-2.3.0-nano.jar. |
|
|
|
|
\<protobuf-root\>java/target/protobuf-java-2.3.0-nano.jar. |
|
|
|
|
- Invoke with --javanano_out, e.g.: |
|
|
|
|
|
|
|
|
|
``` |
|
|
|
|
./protoc '--javanano_out=\ |
|
|
|
|
java_package=src/proto/simple-data.proto|my_package,\ |
|
|
|
|
java_outer_classname=src/proto/simple-data.proto|OuterName\ |
|
|
|
|
:.' src/proto/simple-data.proto |
|
|
|
|
``` |
|
|
|
|
|
|
|
|
|
Contributing to nano: |
|
|
|
|
--------------------- |
|
|
|
|
|
|
|
|
|
Please add/edit tests in NanoTest.java. |
|
|
|
|
|
|
|
|
|
@ -348,7 +367,7 @@ Please run the following steps to test: |
|
|
|
|
- "make -j12" and check for build errors |
|
|
|
|
|
|
|
|
|
Usage |
|
|
|
|
===== |
|
|
|
|
----- |
|
|
|
|
|
|
|
|
|
The complete documentation for Protocol Buffers is available via the |
|
|
|
|
web at: |
Jisi Liu
10 years ago