6ccda5eb20
To make the method smaller and faster. The hot-path assembly code is substantially smaller if it doesn't have to allocate (and handle allocation failure) and throw the exception directly. Take this example: https://godbolt.org/z/EGYefWMEG ```java class Square { public int throwDirectly(int a) { switch (a) { case 1: return 1; } throw new IllegalArgumentException(); } public int throwViaMethod(int a) { switch (a) { case 1: return 1; } return throwIllegalArgumentException(); } public static int throwIllegalArgumentException() { throw new IllegalArgumentException(); } } ``` Outputs dex: ``` # virtual methods .method public throwDirectly(I)I .registers 2 #@0 .line 3 packed-switch p1, :pswitch_data_c #@3 .line 6 new-instance p1, Ljava/lang/IllegalArgumentException; #@5 invoke-direct {p1}, Ljava/lang/IllegalArgumentException;-><init>()V #@8 throw p1 #@9 .line 4 :pswitch_9 const/4 p1, 0x1 #@a return p1 #@b nop #@c :pswitch_data_c .packed-switch 0x1 :pswitch_9 .end packed-switch .end method .method public throwViaMethod(I)I .registers 2 #@0 .line 10 packed-switch p1, :pswitch_data_a #@3 .line 13 invoke-static {}, LSquare;->throwIllegalArgumentException()I #@6 move-result p1 #@7 return p1 #@8 .line 11 :pswitch_8 const/4 p1, 0x1 #@9 return p1 #@a :pswitch_data_a .packed-switch 0x1 :pswitch_8 .end packed-switch .end method ``` Which compiles to substantially smaller oat code (100 bytes before, 52 bytes after): ``` int Square.throwDirectly(int) [100 bytes] 0x00004070 sub x16, sp, #0x2000 (8192) 0x00004074 ldr wzr, [x16] StackMap[0] native_pc=0x4078, dex_pc=0x0, register_mask=0x0, stack_mask=0b 0x00004078 str x0, [sp, #-32]! 0x0000407c stp x22, lr, [sp, #16] 0x00004080 ldr x21, [x21] StackMap[1] native_pc=0x4084, dex_pc=0x0, register_mask=0x2, stack_mask=0b 0x00004084 cmp w2, #0x1 (1) 0x00004088 b.ne #+0x14 (addr 0x0000409c) 0x0000408c mov w0, #0x1 0x00004090 ldp x22, lr, [sp, #16] 0x00004094 add sp, sp, #0x20 (32) 0x00004098 ret 0x0000409c adrp x0, #+0x4000 (addr 0x00008000) 0x000040a0 ldr w0, [x0] 0x000040a4 ldr lr, [tr, #464] ; pAllocObjectInitialized 0x000040a8 blr lr StackMap[2] native_pc=0x40ac, dex_pc=0x4, register_mask=0x0, stack_mask=0b 0x000040ac dmb ishst 0x000040b0 mov x1, x0 0x000040b4 mov x22, x1 0x000040b8 adrp x0, #+0x4000 (addr 0x00008000) 0x000040bc ldr w0, [x0, #4] 0x000040c0 ldr lr, [x0, #24] 0x000040c4 blr lr StackMap[3] native_pc=0x40c8, dex_pc=0x6, register_mask=0x400000, stack_mask=0b 0x000040c8 mov x0, x22 0x000040cc ldr lr, [tr, #1264] ; pDeliverException 0x000040d0 blr lr StackMap[4] native_pc=0x40d4, dex_pc=0x9, register_mask=0x400000, stack_mask=0b int Square.throwViaMethod(int) [52 bytes] 0x000040e0 sub x16, sp, #0x2000 (8192) 0x000040e4 ldr wzr, [x16] StackMap[0] native_pc=0x40e8, dex_pc=0x0, register_mask=0x0, stack_mask=0b 0x000040e8 stp x0, lr, [sp, #-16]! 0x000040ec ldr x21, [x21] StackMap[1] native_pc=0x40f0, dex_pc=0x0, register_mask=0x2, stack_mask=0b 0x000040f0 cmp w2, #0x1 (1) 0x000040f4 b.eq #+0x14 (addr 0x00004108) 0x000040f8 adrp x0, #+0x8000 (addr 0x0000c000) 0x000040fc ldr x0, [x0] 0x00004100 ldr lr, [x0, #24] 0x00004104 blr lr StackMap[2] native_pc=0x4108, dex_pc=0x3, register_mask=0x0, stack_mask=0b 0x00004108 mov w0, #0x1 0x0000410c ldp xzr, lr, [sp], #16 0x00004110 ret ``` PiperOrigin-RevId: 884663197 |
||
|---|---|---|
| .. | ||
| bom | ||
| core | ||
| internal | ||
| kotlin | ||
| kotlin-lite | ||
| lite | ||
| osgi | ||
| protoc | ||
| test/linkage-monitor-check-bom | ||
| util | ||
| BUILD.bazel | ||
| linkage_monitor.sh | ||
| lite.md | ||
| pom.xml | ||
| README.md | ||
Protocol Buffers - Google's data interchange format
Copyright 2008 Google Inc.
https://developers.google.com/protocol-buffers/
Use Java Protocol Buffers
To use protobuf in Java, first obtain the protocol compiler (a.k.a., protoc, see instructions in the toplevel README.md) and use it to generate Java code for your .proto files:
$ protoc --java_out=${OUTPUT_DIR} path/to/your/proto/file
Include the generated Java files in your project and add a dependency on the protobuf Java runtime.
Maven
If you are using Maven, use the following:
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protobuf-java</artifactId>
<version><!--version--></version>
</dependency>
And replace <!--version--> with a version from the
Maven Protocol Buffers Repository.
For example, 4.28.2.
Make sure the version number of the runtime matches (or is newer than) the version number of the protoc.
If you want to use features like protobuf JsonFormat, add a dependency on the protobuf-java-util package:
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protobuf-java-util</artifactId>
<version><!--version--></version>
</dependency>
Use Java Protocol Buffers on Android
For Android users, it's recommended to use protobuf Java Lite runtime because of its smaller code size. Java Lite runtime also works better with Proguard because it doesn't rely on Java reflection and is optimized to allow as much code stripping as possible. You can following these instructions to use Java Lite runtime.
Use Java Protocol Buffers with Bazel
Bazel has native build rules to work with protobuf. For Java, you can use the
java_proto_library rule for server and the java_lite_proto_library rule for
Android. Check out our build files examples to learn
how to use them.
Build from Source
Most users should follow the instructions above to use protobuf Java runtime. If you are contributing code to protobuf or want to use a protobuf version that hasn't been officially released yet, you can follow the instructions below to build protobuf from source code.
Build from Source
You may follow these instructions to build from source. This does not require Maven to be installed. Note that these instructions skip running unit tests and only describes how to install the core protobuf library (without the util package).
-
Build the C++ code, or obtain a binary distribution of protoc (see the toplevel README.md). 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.
-
Invoke protoc to build DescriptorProtos.java:
$ protoc --java_out=core/src/main/java -I../src
../src/google/protobuf/descriptor.proto -
Compile the code in core/src/main/java using whatever means you prefer.
-
Install the classes wherever you prefer.
Kotlin Protocol Buffers
This directory also provides support for Kotlin protocol buffers, which are built on top of Java protocol buffers. Kotlin protocol buffers require a dependency on Java protocol buffers, and both Java and Kotlin protocol buffer code must be generated for every proto file.
The main goal of Kotlin protobuf is to provide idiomatic ways to build and read protocol buffers in Kotlin. Learn more about Kotlin protobufs in our documentation.
Use Kotlin Protocol Buffers
To use protobuf in Kotlin, first install the protocol compiler (protoc -- instructions for installing are in the top-level README.md) and use it to generate Java and Kotlin code for your .proto files:
$ protoc --java_out=${OUTPUT_DIR} --kotlin_out=${OUTPUT_DIR} path/to/your/proto/file
Include the generated Java and Kotlin files in your project and add a dependency on the protobuf Java and Kotlin runtime.
Maven
If you are using Maven, use the following:
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protobuf-java</artifactId>
<version><!--version--></version>
</dependency>
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protobuf-kotlin</artifactId>
<version><!--version--></version>
</dependency>
Replace <!--version--> with a version from the
Maven Protocol Buffers Repository,
such as 4.28.2.
Make sure the version number of the runtimes match each other and match (or are newer than) the version number of the protoc.
Use Kotlin Protocol Buffers on Android
For Android users, it's recommended to use the Java Lite runtime for its smaller
code size. We provide a protobuf-kotlin-lite package in Maven and Bazel to
pair with the Java Lite runtime. Use these if you want to use Kotlin on
Android or in another context where you want to use Java Lite. Similar to the
full runtime, protobuf-kotlin-lite requires a dependency on
protobuf-java-lite.
Compatibility Notice
-
Protobuf minor version releases are backwards-compatible. If your code can build/run against the old version, it's expected to build/run against the new version as well. Both binary compatibility and source compatibility are guaranteed for minor version releases if the user follows the guideline described in this section.
-
Protobuf major version releases may also be backwards-compatible with the last release of the previous major version. See the release notice for more details.
-
APIs marked with the @ExperimentalApi annotation are subject to change. They can be modified in any way, or even removed, at any time. Don't use them if compatibility is needed. If your code is a library itself (i.e. it is used on the CLASSPATH of users outside your own control), you should not use experimental APIs, unless you repackage them (e.g. using ProGuard).
-
Deprecated non-experimental APIs will be removed two years after the release in which they are first deprecated. You must fix your references before this time. If you don't, any manner of breakage could result (you are not guaranteed a compilation error).
-
Protobuf message interfaces/classes are designed to be subclassed by protobuf generated code only. Do not subclass these message interfaces/classes yourself. We may add new methods to the message interfaces/classes which will break your own subclasses.
-
Don't use any method/class that is marked as "used by generated code only". Such methods/classes are subject to change.
-
Protobuf LITE runtime APIs are not stable yet. They are subject to change even in minor version releases.
Documentation
The complete documentation for Protocol Buffers is available via the web at: