• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Protocol Buffers - Google's data interchange format
2===================================================
3
4[![Build Status](https://travis-ci.org/google/protobuf.svg?branch=master)](https://travis-ci.org/google/protobuf)
5
6Copyright 2008 Google Inc.
7
8This directory contains the Java Protocol Buffers Nano runtime library.
9
10Installation - With Maven
11-------------------------
12
13The Protocol Buffers build is managed using Maven.  If you would
14rather build without Maven, see below.
15
161) Install Apache Maven if you don't have it:
17
18     http://maven.apache.org/
19
202) 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
293) 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
364) Install the library into your Maven repository:
37
38     $ mvn install
39
405) 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
47Installation - Without Maven
48----------------------------
49
50If you would rather not install Maven to build the library, you may
51follow these instructions instead.  Note that these instructions skip
52running unit tests.
53
541) 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
632) Invoke protoc to build DescriptorProtos.java:
64
65     $ protoc --java_out=src/main/java -I../src \
66         ../src/google/protobuf/descriptor.proto
67
683) Compile the code in src/main/java using whatever means you prefer.
69
704) Install the classes wherever you prefer.
71
72Nano version
73------------
74
75JavaNano is a special code generator and runtime library designed specially for
76resource-restricted systems, like Android. It is very resource-friendly in both
77the amount of code and the runtime overhead. Here is an overview of JavaNano
78features 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
105The generated messages are not thread-safe for writes, but may be
106used simultaneously from multiple threads in a read-only manner.
107In other words, an appropriate synchronization mechanism (such as
108a ReadWriteLock) must be used to ensure that a message, its
109ancestors, and descendants are not accessed by any other threads
110while the message is being modified. Field reads, getter methods
111(but not getExtension(...)), toByteArray(...), writeTo(...),
112getCachedSize(), and getSerializedSize() are all considered read-only
113operations.
114
115IMPORTANT: If you have fields with defaults and opt out of accessors
116
117How fields with defaults are serialized has changed. Because we don't
118keep "has" state, any field equal to its default is assumed to be not
119set and therefore is not serialized. Consider the situation where we
120change the default value of a field. Senders compiled against an older
121version of the proto continue to match against the old default, and
122don't send values to the receiver even though the receiver assumes the
123new default value. Therefore, think carefully about the implications
124of changing the default value. Alternatively, turn on accessors and
125enjoy the benefit of the explicit has() checks.
126
127IMPORTANT: If you have "bytes" fields with non-empty defaults
128
129Because the byte buffer is now of mutable type byte[], the default
130static final cannot be exposed through a public field. Each time a
131message's constructor or clear() function is called, the default value
132(kept in a private byte[]) is cloned. This causes a small memory
133penalty. This is not a problem if the field has no default or is an
134empty default.
135
136Nano Generator options
137----------------------
138
139```
140java_package           -> <file-name>|<package-name>
141java_outer_classname   -> <file-name>|<package-name>
142java_multiple_files    -> true or false
143java_nano_generate_has -> true or false [DEPRECATED]
144optional_field_style   -> default or accessors
145enum_style             -> c or java
146ignore_services        -> true or false
147parcelable_messages    -> true or false
148generate_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
329To 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
354To 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
367Contributing to nano:
368---------------------
369
370Please add/edit tests in NanoTest.java.
371
372Please 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
392Usage
393-----
394
395The complete documentation for Protocol Buffers is available via the
396web at:
397
398    https://developers.google.com/protocol-buffers/
399