1# Protocol Buffers - Google's data interchange format 2 3Copyright 2008 Google Inc. 4 5https://developers.google.com/protocol-buffers/ 6 7## Use Java Protocol Buffers 8 9To use protobuf in Java, first obtain the protocol compiler (a.k.a., protoc, 10see instructions in the toplevel [README.md](../README.md)) and use it to 11generate Java code for your .proto files: 12 13 $ protoc --java_out=${OUTPUT_DIR} path/to/your/proto/file 14 15Include the generated Java files in your project and add a dependency on the 16protobuf Java runtime. 17 18### Maven 19 20If you are using Maven, use the following: 21 22```xml 23<dependency> 24 <groupId>com.google.protobuf</groupId> 25 <artifactId>protobuf-java</artifactId> 26 <version>3.6.1</version> 27</dependency> 28``` 29 30Make sure the version number of the runtime matches (or is newer than) the 31version number of the protoc. 32 33If you want to use features like protobuf JsonFormat, add a dependency on the 34protobuf-java-util package: 35 36```xml 37<dependency> 38 <groupId>com.google.protobuf</groupId> 39 <artifactId>protobuf-java-util</artifactId> 40 <version>3.6.1</version> 41</dependency> 42``` 43 44### Gradle 45 46If you are using Gradle, add the following to your `build.gradle` file's dependencies: 47``` 48 compile 'com.google.protobuf:protobuf-java:3.6.1' 49``` 50Again, be sure to check that the version number maches (or is newer than) the version number of protoc that you are using. 51 52### Use Java Protocol Buffers on Android 53 54For Android users, it's recommended to use protobuf Java Lite runtime because 55of its smaller code size. Java Lite runtime also works better with Proguard 56because it doesn't rely on Java reflection and is optimized to allow as much 57code stripping as possible. You can following these [instructions to use Java 58Lite runtime](lite.md). 59 60### Use Java Protocol Buffers with Bazel 61 62Bazel has native build rules to work with protobuf. For Java, you can use the 63`java_proto_library` rule for server and the `java_lite_proto_library` rule 64for Android. Check out [our build files examples](../examples/BUILD) to learn 65how to use them. 66 67## Build from Source 68 69Most users should follow the instructions above to use protobuf Java runtime. 70If you are contributing code to protobuf or want to use a protobuf version 71that hasn't been officially released yet, you can folllow the instructions 72below to build protobuf from source code. 73 74### Build from Source - With Maven 75 761) Install Apache Maven if you don't have it: 77 78 http://maven.apache.org/ 79 802) Build the C++ code, or obtain a binary distribution of protoc (see 81 the toplevel [README.md](../README.md)). If you install a binary 82 distribution, make sure that it is the same version as this package. 83 If in doubt, run: 84 85 $ protoc --version 86 87 You will need to place the protoc executable in ../src. (If you 88 built it yourself, it should already be there.) 89 903) Run the tests: 91 92 $ mvn test 93 94 If some tests fail, this library may not work correctly on your 95 system. Continue at your own risk. 96 974) Install the library into your Maven repository: 98 99 $ mvn install 100 1015) If you do not use Maven to manage your own build, you can build a 102 .jar file to use: 103 104 $ mvn package 105 106 The .jar will be placed in the "target" directory. 107 108The above instructions will install 2 maven artifacts: 109 110 * protobuf-java: The core Java Protocol Buffers library. Most users only 111 need this artifact. 112 * protobuf-java-util: Utilities to work with protos. It contains JSON support 113 as well as utilities to work with proto3 well-known 114 types. 115 116### Build from Source - Without Maven 117 118If you would rather not install Maven to build the library, you may 119follow these instructions instead. Note that these instructions skip 120running unit tests and only describes how to install the core protobuf 121library (without the util package). 122 1231) Build the C++ code, or obtain a binary distribution of protoc. If 124 you install a binary distribution, make sure that it is the same 125 version as this package. If in doubt, run: 126 127 $ protoc --version 128 129 If you built the C++ code without installing, the compiler binary 130 should be located in ../src. 131 1322) Invoke protoc to build DescriptorProtos.java: 133 134 $ protoc --java_out=core/src/main/java -I../src \ 135 ../src/google/protobuf/descriptor.proto 136 1373) Compile the code in core/src/main/java using whatever means you prefer. 138 1394) Install the classes wherever you prefer. 140 141## Compatibility Notice 142 143* Protobuf minor version releases are backwards-compatible. If your code 144 can build/run against the old version, it's expected to build/run against 145 the new version as well. Both binary compatibility and source compatibility 146 are guaranteed for minor version releases if the user follows the guideline 147 described in this section. 148 149* Protobuf major version releases may also be backwards-compatbile with the 150 last release of the previous major version. See the release notice for more 151 details. 152 153* APIs marked with the @ExperimentalApi annotation are subject to change. They 154 can be modified in any way, or even removed, at any time. Don't use them if 155 compatibility is needed. If your code is a library itself (i.e. it is used on 156 the CLASSPATH of users outside your own control), you should not use 157 experimental APIs, unless you repackage them (e.g. using ProGuard). 158 159* Deprecated non-experimental APIs will be removed two years after the release 160 in which they are first deprecated. You must fix your references before this 161 time. If you don't, any manner of breakage could result (you are not 162 guaranteed a compilation error). 163 164* Protobuf message interfaces/classes are designed to be subclassed by protobuf 165 generated code only. Do not subclass these message interfaces/classes 166 yourself. We may add new methods to the message interfaces/classes which will 167 break your own subclasses. 168 169* Don't use any method/class that is marked as "used by generated code only". 170 Such methods/classes are subject to change. 171 172* Protobuf LITE runtime APIs are not stable yet. They are subject to change even 173 in minor version releases. 174 175## Documentation 176 177The complete documentation for Protocol Buffers is available via the 178web at: 179 180 https://developers.google.com/protocol-buffers/ 181