protobuf-3.0.0-alpha-3.1

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. 1) Install Apache Maven if you don't have it: http://maven.apache.org/ 2) Build the C++ code, or obtain a binary distribution of protoc. If you install a binary distribution, make sure that it is the same version as this package. If in doubt, run: $ protoc --version You will need to place the protoc executable in ../src. (If you built it yourself, it should already be there.) 3) Run the tests: $ mvn test If some tests fail, this library may not work correctly on your system. Continue at your own risk. 4) Install the library into your Maven repository: $ mvn install 5) If you do not use Maven to manage your own build, you can build a .jar file to use: $ mvn package 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 running unit tests. 1) Build the C++ code, or obtain a binary distribution of protoc. If you install a binary distribution, make sure that it is the same version as this package. If in doubt, run: $ protoc --version If you built the C++ code without installing, the compiler binary should be located in ../src. 2) Invoke protoc to build DescriptorProtos.java: $ protoc --java_out=src/main/java -I../src \ ../src/google/protobuf/descriptor.proto 3) Compile the code in src/main/java using whatever means you prefer. 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 the amount of code and the runtime overhead. Here is an overview of JavaNano features compared with the official Java protobuf: - No descriptors or message builders. - All messages are mutable; fields are public Java fields. - For optional fields only, encapsulation behind setter/getter/hazzer/ clearer functions is opt-in, which provide proper 'has' state support. - For proto2, if not opted in, has state (field presence) is not available. Serialization outputs all fields not equal to their defaults (see important implications below). The behavior is consistent with proto3 semantics. - Required fields (proto2 only) are always serialized. - Enum constants are integers; protection against invalid values only when parsing from the wire. - Enum constants can be generated into container interfaces bearing the enum's name (so the referencing code is in Java style). - CodedInputByteBufferNano can only take byte[] (not InputStream). - Similarly CodedOutputByteBufferNano can only write to byte[]. - Repeated fields are in arrays, not ArrayList or Vector. Null array elements are allowed and silently ignored. - Full support for serializing/deserializing repeated packed fields. - Support extensions (in proto2). - Unset messages/groups are null, not an immutable empty default instance. - toByteArray(...) and mergeFrom(...) are now static functions of MessageNano. - The 'bytes' type translates to the Java type byte[]. The generated messages are not thread-safe for writes, but may be used simultaneously from multiple threads in a read-only manner. In other words, an appropriate synchronization mechanism (such as a ReadWriteLock) must be used to ensure that a message, its ancestors, and descendants are not accessed by any other threads while the message is being modified. Field reads, getter methods (but not getExtension(...)), toByteArray(...), writeTo(...), getCachedSize(), and getSerializedSize() are all considered read-only operations. IMPORTANT: If you have fields with defaults and opt out of accessors How fields with defaults are serialized has changed. Because we don't keep "has" state, any field equal to its default is assumed to be not set and therefore is not serialized. Consider the situation where we change the default value of a field. Senders compiled against an older version of the proto continue to match against the old default, and don't send values to the receiver even though the receiver assumes the new default value. Therefore, think carefully about the implications of changing the default value. Alternatively, turn on accessors and enjoy the benefit of the explicit has() checks. IMPORTANT: If you have "bytes" fields with non-empty defaults Because the byte buffer is now of mutable type byte[], the default static final cannot be exposed through a public field. Each time a message's constructor or clear() function is called, the default value (kept in a private byte[]) is cloned. This causes a small memory 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 java_nano_generate_has -> true or false [DEPRECATED] optional_field_style -> default or accessors enum_style -> c or java ignore_services -> true or false parcelable_messages -> true or false generate_intdefs -> true or false ``` **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 files. The final Java package for each file is the value of this command line option if present, or the value of 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) 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 multiple files. The final Java outer class name for each file is the value of this command line option if present, or the value of the same option defined in the file if present, or the file name converted to CamelCase. This outer class will nest all classes and integer constants generated from file-scope messages and enums. **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 file is the value defined in this command line option, or the value of the same option defined in the file if present, or false. This specifies whether to generate package-level classes for the file-scope messages in the same Java package as the outer class (instead of nested classes in the outer class). File-scope enum constants are still generated as integer constants in the outer class. This affects the fully qualified references in the Java code. NOTE: because the command line option overrides the value for all files and their imported files, using this option inconsistently may result in incorrect references to the imported messages and enum constants. **java_nano_generate_has={true,false}** (default: false) DEPRECATED. Use optional_field_style=accessors. If true, generates a public boolean variable has\<fieldname\> accompanying each optional or required field (not present for repeated fiel