1 Protocol Buffers - Google's data interchange format 2 =================================================== 3 4 [](https://travis-ci.org/google/protobuf) 5 6 Copyright 2008 Google Inc. 7 8 This directory contains the Java Protocol Buffers Nano runtime library. 9 10 Installation - With Maven 11 ------------------------- 12 13 The Protocol Buffers build is managed using Maven. If you would 14 rather build without Maven, see below. 15 16 1) Install Apache Maven if you don't have it: 17 18 http://maven.apache.org/ 19 20 2) Build the C++ code, or obtain a binary distribution of protoc. If 21 you install a binary distribution, make sure that it is the same 22 version as this package. If in doubt, run: 23 24 $ protoc --version 25 26 You will need to place the protoc executable in ../src. (If you 27 built it yourself, it should already be there.) 28 29 3) Run the tests: 30 31 $ mvn test 32 33 If some tests fail, this library may not work correctly on your 34 system. Continue at your own risk. 35 36 4) Install the library into your Maven repository: 37 38 $ mvn install 39 40 5) If you do not use Maven to manage your own build, you can build a 41 .jar file to use: 42 43 $ mvn package 44 45 The .jar will be placed in the "target" directory. 46 47 Installation - Without Maven 48 ---------------------------- 49 50 If you would rather not install Maven to build the library, you may 51 follow these instructions instead. Note that these instructions skip 52 running unit tests. 53 54 1) Build the C++ code, or obtain a binary distribution of protoc. If 55 you install a binary distribution, make sure that it is the same 56 version as this package. If in doubt, run: 57 58 $ protoc --version 59 60 If you built the C++ code without installing, the compiler binary 61 should be located in ../src. 62 63 2) Invoke protoc to build DescriptorProtos.java: 64 65 $ protoc --java_out=src/main/java -I../src \ 66 ../src/google/protobuf/descriptor.proto 67 68 3) Compile the code in src/main/java using whatever means you prefer. 69 70 4) Install the classes wherever you prefer. 71 72 Nano version 73 ------------ 74 75 JavaNano is a special code generator and runtime library designed specially for 76 resource-restricted systems, like Android. It is very resource-friendly in both 77 the amount of code and the runtime overhead. Here is an overview of JavaNano 78 features compared with the official Java protobuf: 79 80 - No descriptors or message builders. 81 - All messages are mutable; fields are public Java fields. 82 - For optional fields only, encapsulation behind setter/getter/hazzer/ 83 clearer functions is opt-in, which provide proper 'has' state support. 84 - For proto2, if not opted in, has state (field presence) is not available. 85 Serialization outputs all fields not equal to their defaults 86 (see important implications below). 87 The behavior is consistent with proto3 semantics. 88 - Required fields (proto2 only) are always serialized. 89 - Enum constants are integers; protection against invalid values only 90 when parsing from the wire. 91 - Enum constants can be generated into container interfaces bearing 92 the enum's name (so the referencing code is in Java style). 93 - CodedInputByteBufferNano can only take byte[] (not InputStream). 94 - Similarly CodedOutputByteBufferNano can only write to byte[]. 95 - Repeated fields are in arrays, not ArrayList or Vector. Null array 96 elements are allowed and silently ignored. 97 - Full support for serializing/deserializing repeated packed fields. 98 - Support extensions (in proto2). 99 - Unset messages/groups are null, not an immutable empty default 100 instance. 101 - toByteArray(...) and mergeFrom(...) are now static functions of 102 MessageNano. 103 - The 'bytes' type translates to the Java type byte[]. 104 105 The generated messages are not thread-safe for writes, but may be 106 used simultaneously from multiple threads in a read-only manner. 107 In other words, an appropriate synchronization mechanism (such as 108 a ReadWriteLock) must be used to ensure that a message, its 109 ancestors, and descendants are not accessed by any other threads 110 while the message is being modified. Field reads, getter methods 111 (but not getExtension(...)), toByteArray(...), writeTo(...), 112 getCachedSize(), and getSerializedSize() are all considered read-only 113 operations. 114 115 IMPORTANT: If you have fields with defaults and opt out of accessors 116 117 How fields with defaults are serialized has changed. Because we don't 118 keep "has" state, any field equal to its default is assumed to be not 119 set and therefore is not serialized. Consider the situation where we 120 change the default value of a field. Senders compiled against an older 121 version of the proto continue to match against the old default, and 122 don't send values to the receiver even though the receiver assumes the 123 new default value. Therefore, think carefully about the implications 124 of changing the default value. Alternatively, turn on accessors and 125 enjoy the benefit of the explicit has() checks. 126 127 IMPORTANT: If you have "bytes" fields with non-empty defaults 128 129 Because the byte buffer is now of mutable type byte[], the default 130 static final cannot be exposed through a public field. Each time a 131 message's constructor or clear() function is called, the default value 132 (kept in a private byte[]) is cloned. This causes a small memory 133 penalty. This is not a problem if the field has no default or is an 134 empty default. 135 136 Nano Generator options 137 ---------------------- 138 139 ``` 140 java_package -> <file-name>|<package-name> 141 java_outer_classname -> <file-name>|<package-name> 142 java_multiple_files -> true or false 143 java_nano_generate_has -> true or false [DEPRECATED] 144 optional_field_style -> default or accessors 145 enum_style -> c or java 146 ignore_services -> true or false 147 parcelable_messages -> true or false 148 generate_intdefs -> true or false 149 ``` 150 151 **java_package=\<file-name\>|\<package-name\>** (no default) 152 153 This allows overriding the 'java_package' option value 154 for the given file from the command line. Use multiple 155 java_package options to override the option for multiple 156 files. The final Java package for each file is the value 157 of this command line option if present, or the value of 158 the same option defined in the file if present, or the 159 proto package if present, or the default Java package. 160 161 **java_outer_classname=\<file-name\>|\<outer-classname\>** (no default) 162 163 This allows overriding the 'java_outer_classname' option 164 for the given file from the command line. Use multiple 165 java_outer_classname options to override the option for 166 multiple files. The final Java outer class name for each 167 file is the value of this command line option if present, 168 or the value of the same option defined in the file if 169 present, or the file name converted to CamelCase. This 170 outer class will nest all classes and integer constants 171 generated from file-scope messages and enums. 172 173 **java_multiple_files={true,false}** (no default) 174 175 This allows overriding the 'java_multiple_files' option 176 in all source files and their imported files from the 177 command line. The final value of this option for each 178 file is the value defined in this command line option, or 179 the value of the same option defined in the file if 180 present, or false. This specifies whether to generate 181 package-level classes for the file-scope messages in the 182 same Java package as the outer class (instead of nested 183 classes in the outer class). File-scope enum constants 184 are still generated as integer constants in the outer 185 class. This affects the fully qualified references in the 186 Java code. NOTE: because the command line option 187 overrides the value for all files and their imported 188 files, using this option inconsistently may result in 189 incorrect references to the imported messages and enum 190 constants. 191 192 **java_nano_generate_has={true,false}** (default: false) 193 194 DEPRECATED. Use optional_field_style=accessors. 195 196 If true, generates a public boolean variable has\<fieldname\> 197 accompanying each optional or required field (not present for 198 repeated fields, groups or messages). It is set to false initially 199 and upon clear(). If parseFrom(...) reads the field from the wire, 200 it is set to true. This is a way for clients to inspect the "has" 201 value upon parse. If it is set to true, writeTo(...) will ALWAYS 202 output that field (even if field value is equal to its 203 default). 204 205 IMPORTANT: This option costs an extra 4 bytes per primitive field in 206 the message. Think carefully about whether you really need this. In 207 many cases reading the default works and determining whether the 208 field was received over the wire is irrelevant. 209 210 **optional_field_style={default,accessors,reftypes}** (default: default) 211 212 Defines the style of the generated code for fields. 213 214 * default 215 216 In the default style, optional fields translate into public mutable 217 Java fields, and the serialization process is as discussed in the 218 "IMPORTANT" section above. 219 220 * accessors 221 222 When set to 'accessors', each optional field is encapsulated behind 223 4 accessors, namely get\<fieldname\>(), set\<fieldname\>(), has\<fieldname\>() 224 and clear\<fieldname\>() methods, with the standard semantics. The hazzer's 225 return value determines whether a field is serialized, so this style is 226 useful when you need to serialize a field with the default value, or check 227 if a field has been explicitly set to its default value from the wire. 228 229 In the 'accessors' style, required and nested message fields are still 230 translated to one public mutable Java field each, repeated fields are still 231 translated to arrays. No accessors are generated for them. 232 233 IMPORTANT: When using the 'accessors' style, ProGuard should always 234 be enabled with optimization (don't use -dontoptimize) and allowing 235 access modification (use -allowaccessmodification). This removes the 236 unused accessors and maybe inline the rest at the call sites, 237 reducing the final code size. 238 TODO(maxtroy): find ProGuard config that would work the best. 239 240 * reftypes 241 242 When set to 'reftypes', each proto field is generated as a public Java 243 field. For primitive types, these fields use the Java reference types 244 such as java.lang.Integer instead of primitive types such as int. 245 246 In the 'reftypes' style, fields are initialized to null (or empty 247 arrays for repeated fields), and their default values are not available. 248 They are serialized over the wire based on equality to null. 249 250 The 'reftypes' mode has some additional cost due to autoboxing and usage 251 of reference types. In practice, many boxed types are cached, and so don't 252 result in object creation. However, references do take slightly more memory 253 than primitives. 254 255 The 'reftypes' mode is useful when you want to be able to serialize fields 256 with default values, or check if a field has been explicitly set to the 257 default over the wire without paying the extra method cost of the 258 'accessors' mode. 259 260 Note that if you attempt to write null to a required field in the reftypes 261 mode, serialization of the proto will cause a NullPointerException. This is 262 an intentional indicator that you must set required fields. 263 264 NOTE 265 optional_field_style=accessors or reftypes cannot be used together with 266 java_nano_generate_has=true. If you need the 'has' flag for any 267 required field (you have no reason to), you can only use 268 java_nano_generate_has=true. 269 270 **enum_style={c,java}** (default: c) 271 272 Defines where to put the int constants generated from enum members. 273 274 * c 275 276 Use C-style, so the enum constants are available at the scope where 277 the enum is defined. A file-scope enum's members are referenced like 278 'FileOuterClass.ENUM_VALUE'; a message-scope enum's members are 279 referenced as 'Message.ENUM_VALUE'. The enum name is unavailable. 280 This complies with the Micro code generator's behavior. 281 282 * java 283 284 Use Java-style, so the enum constants are available under the enum 285 name and referenced like 'EnumName.ENUM_VALUE' (they are still int 286 constants). The enum name becomes the name of a public interface, at 287 the scope where the enum is defined. If the enum is file-scope and 288 the java_multiple_files option is on, the interface will be defined 289 in its own file. To reduce code size, this interface should not be 290 implemented and ProGuard shrinking should be used, so after the Java 291 compiler inlines all referenced enum constants into the call sites, 292 the interface remains unused and can be removed by ProGuard. 293 294 **ignore_services={true,false}** (default: false) 295 296 Skips services definitions. 297 298 Nano doesn't support services. By default, if a service is defined 299 it will generate a compilation error. If this flag is set to true, 300 services will be silently ignored, instead. 301 302 **parcelable_messages={true,false}** (default: false) 303 304 Android-specific option to generate Parcelable messages. 305 306 **generate_intdefs={true,false}** (default: false) 307 Android-specific option to generate @IntDef annotations for enums. 308 309 If turned on, an '@IntDef' annotation (a public @interface) will be 310 generated for each enum, and every integer parameter and return 311 value in the generated code meant for this enum will be annotated 312 with it. This interface is generated with the same name and at the 313 same place as the enum members' container interfaces described 314 above under 'enum_style=java', regardless of the enum_style option 315 used. When this is combined with enum_style=java, the interface 316 will be both the '@IntDef' annotation and the container of the enum 317 members; otherwise the interface has an empty body. 318 319 Your app must declare a compile-time dependency on the 320 android-support-annotations library. 321 322 For more information on how these @IntDef annotations help with 323 compile-time type safety, see: 324 https://sites.google.com/a/android.com/tools/tech-docs/support-annotations 325 and 326 https://developer.android.com/reference/android/support/annotation/IntDef.html 327 328 329 To use nano protobufs within the Android repo: 330 ---------------------------------------------- 331 332 - Set 'LOCAL_PROTOC_OPTIMIZE_TYPE := nano' in your local .mk file. 333 When building a Java library or an app (package) target, the build 334 system will add the Java nano runtime library to the 335 LOCAL_STATIC_JAVA_LIBRARIES variable, so you don't need to. 336 - Set 'LOCAL_PROTO_JAVA_OUTPUT_PARAMS := ...' in your local .mk file 337 for any command-line options you need. Use commas to join multiple 338 options. In the nano flavor only, whitespace surrounding the option 339 names and values are ignored, so you can use backslash-newline or 340 '+=' to structure your make files nicely. 341 - The options will be applied to *all* proto files in LOCAL_SRC_FILES 342 when you build a Java library or package. In case different options 343 are needed for different proto files, build separate Java libraries 344 and reference them in your main target. Note: you should make sure 345 that, for each separate target, all proto files imported from any 346 proto file in LOCAL_SRC_FILES are included in LOCAL_SRC_FILES. This 347 is because the generator has to assume that the imported files are 348 built using the same options, and will generate code that reference 349 the fields and enums from the imported files using the same code 350 style. 351 - Hint: 'include $(CLEAR_VARS)' resets all LOCAL_ variables, including 352 the two above. 353 354 To use nano protobufs outside of Android repo: 355 ---------------------------------------------- 356 357 - Link with the generated jar file 358 \<protobuf-root\>java/target/protobuf-java-2.3.0-nano.jar. 359 - Invoke with --javanano_out, e.g.: 360 ``` 361 ./protoc '--javanano_out=\ 362 java_package=src/proto/simple-data.proto|my_package,\ 363 java_outer_classname=src/proto/simple-data.proto|OuterName\ 364 :.' src/proto/simple-data.proto 365 ``` 366 367 Contributing to nano: 368 --------------------- 369 370 Please add/edit tests in NanoTest.java. 371 372 Please run the following steps to test: 373 374 - cd external/protobuf 375 - ./configure 376 - Run "make -j12 check" and verify all tests pass. 377 - cd java 378 - Run "mvn test" and verify all tests pass. 379 - cd ../../.. 380 - . build/envsetup.sh 381 - lunch 1 382 - "make -j12 aprotoc libprotobuf-java-2.3.0-nano aprotoc-test-nano-params NanoAndroidTest" and 383 check for build errors. 384 - Plug in an Android device or start an emulator. 385 - adb install -r out/target/product/generic/data/app/NanoAndroidTest.apk 386 - Run: 387 "adb shell am instrument -w com.google.protobuf.nano.test/android.test.InstrumentationTestRunner" 388 and verify all tests pass. 389 - repo sync -c -j256 390 - "make -j12" and check for build errors 391 392 Usage 393 ----- 394 395 The complete documentation for Protocol Buffers is available via the 396 web at: 397 398 https://developers.google.com/protocol-buffers/ 399
