From 2337023fd9686b61f73f91588583685abf7d5773 Mon Sep 17 00:00:00 2001
From: Ulas Kirazci <ulas@google.com>
Date: Thu, 14 Mar 2013 16:44:33 -0700
Subject: Nano protobufs.

Like micro protobufs except:

- No setter/getter/hazzer functions.
- Has state is not available. Outputs all fields != their default.
- CodedInputStream can only take byte[] (not InputStream).
- Repeated fields are in arrays, not ArrayList or Vector.
- Unset messages/groups are null, not "defaultInstance()".
- Required fields are always serialized.

To use:

- Link libprotobuf-java-2.3.0-nano runtime.
- Use LOCAL_PROTOC_OPTIMIZE_TYPE := nano

Change-Id: I7429015b3c5f7f38b7be01eb2d4927f7a9999c80
---
 java/README.txt | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 51 insertions(+)

(limited to 'java/README.txt')

diff --git a/java/README.txt b/java/README.txt
index 8972792d..82c1ed53 100644
--- a/java/README.txt
+++ b/java/README.txt
@@ -260,6 +260,57 @@ This could be compiled using:
 With the result will be com/example/TestMessages.java
 
 
+Nano version
+============================
+
+Nano is even smaller than micro, especially in the number of generated
+functions. It is like micro except:
+
+- No setter/getter/hazzer functions.
+- Has state is not available. Outputs all fields not equal to their
+  default. (See important implications below.)
+- CodedInputStreamMicro is renamed to CodedInputByteBufferNano and can
+  only take byte[] (not InputStream).
+- Similar rename from CodedOutputStreamMicro to
+  CodedOutputByteBufferNano.
+- Repeated fields are in arrays, not ArrayList or Vector.
+- Unset messages/groups are null, not an immutable empty default
+  instance.
+- Required fields are always serialized.
+- toByteArray(...) and mergeFrom(...) are now static functions of
+  MessageNano.
+- "bytes" are of java type byte[].
+
+IMPORTANT: If you have fields with defaults
+
+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.
+
+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.
+
+
+To use nano protobufs:
+
+- Link with the generated jar file
+  <protobuf-root>java/target/protobuf-java-2.3.0-nano.jar.
+- Invoke with --javanano_out, e.g.:
+
+../src/protoc '--javanano_out=java_package=src/test/proto/simple-data.proto|my_package,java_outer_classname=src/test/proto/simple-data.proto|OuterName:.' src/test/proto/simple-data.proto
+
+
 Usage
 =====
 
-- 
cgit v1.2.3