java/README.md

   1 # Protocol Buffers - Google's data interchange format
   2
   3 Copyright 2008 Google Inc.
   4
   5 https://developers.google.com/protocol-buffers/
   6
   7 ## Use Java Protocol Buffers
   8
   9 To use protobuf in Java, first obtain the protocol compiler (a.k.a., protoc,
  10 see instructions in the toplevel [README.md](../README.md)) and use it to
  11 generate Java code for your .proto files:
  12
  13     $ protoc --java_out=${OUTPUT_DIR} path/to/your/proto/file
  14
  15 Include the generated Java files in your project and add a dependency on the
  16 protobuf Java runtime.
  17
  18 ### Maven
  19
  20 If 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
  30 Make sure the version number of the runtime matches (or is newer than) the
  31 version number of the protoc.
  32
  33 If you want to use features like protobuf JsonFormat, add a dependency on the
  34 protobuf-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
  46 If 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 ```
  50 Again, 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
  54 For Android users, it's recommended to use protobuf Java Lite runtime because
  55 of its smaller code size. Java Lite runtime also works better with Proguard
  56 because it doesn't rely on Java reflection and is optimized to allow as much
  57 code stripping as possible. You can following these [instructions to use Java
  58 Lite runtime](lite.md).
  59
  60 ### Use Java Protocol Buffers with Bazel
  61
  62 Bazel 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
  64 for Android. Check out [our build files examples](../examples/BUILD) to learn
  65 how to use them.
  66
  67 ## Build from Source
  68
  69 Most users should follow the instructions above to use protobuf Java runtime.
  70 If you are contributing code to protobuf or want to use a protobuf version
  71 that hasn't been officially released yet, you can folllow the instructions
  72 below to build protobuf from source code.
  73
  74 ### Build from Source - With Maven
  75
  76 1) Install Apache Maven if you don't have it:
  77
  78      http://maven.apache.org/
  79
  80 2) 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
  90 3) 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
  97 4) Install the library into your Maven repository:
  98
  99      $ mvn install
 100
 101 5) 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
 108 The 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
 118 If you would rather not install Maven to build the library, you may
 119 follow these instructions instead.  Note that these instructions skip
 120 running unit tests and only describes how to install the core protobuf
 121 library (without the util package).
 122
 123 1) 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
 132 2) Invoke protoc to build DescriptorProtos.java:
 133
 134      $ protoc --java_out=core/src/main/java -I../src \
 135          ../src/google/protobuf/descriptor.proto
 136
 137 3) Compile the code in core/src/main/java using whatever means you prefer.
 138
 139 4) 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
 177 The complete documentation for Protocol Buffers is available via the
 178 web at:
 179
 180   https://developers.google.com/protocol-buffers/