organicmaps/protobuf
13
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity Actions

Add compatibility notice for Java.

Browse source
This commit is contained in:
Feng Xiao 2016-05-11 16:22:30 -07:00
parent a1938b2aa9
commit 09732c96ac
1 changed files with 55 additions and 30 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

85
java/README.md
View file

@ -17,9 +17,10 @@ rather build without Maven, see below.
http://maven.apache.org/
2) Build the C++ code, or obtain a binary distribution of protoc. If
you install a binary distribution, make sure that it is the same
version as this package. If in doubt, run:
2) Build the C++ code, or obtain a binary distribution of protoc (see
the toplevel [README.md](../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
@ -44,36 +45,25 @@ rather build without Maven, see below.
The .jar will be placed in the "target" directory.
Installation - 'Lite' Version - With Maven
==========================================
The above instructions will install 3 maven artifacts:
Building the 'lite' version of the Java Protocol Buffers library is
the same as building the full version, except that all commands are
run using the 'lite' profile. (see
http://maven.apache.org/guides/introduction/introduction-to-profiles.html)
E.g. to install the lite version of the jar, you would run:
$ mvn install -P lite
The resulting artifact has the 'lite' classifier. To reference it
for dependency resolution, you would specify it as:
```
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protobuf-java</artifactId>
<version>${version}</version>
<classifier>lite</classifier>
</dependency>
```
* protobuf-java: The core Java Protocol Buffers library. Most users only
need this artifact.
* protobuf-lite: The lite version of core Java Protobuf Buffers library. It
is a subset of the core library and is used together with
the 'lite' code generator flag to reduce generated code size
for mobile.
* protobuf-java-util: Utilities to work with protos. It contains JSON support
as well as utilities to work with proto3 well-known
types.
Installation - Without Maven
============================
If you would rather not install Maven to build the library, you may
follow these instructions instead. Note that these instructions skip
running unit tests.
running unit tests and only describes how to install the core protobuf
library (without the util package).
1) Build the C++ code, or obtain a binary distribution of protoc. If
you install a binary distribution, make sure that it is the same
@ -86,15 +76,50 @@ running unit tests.
2) Invoke protoc to build DescriptorProtos.java:
$ protoc --java_out=src/main/java -I../src \
$ protoc --java_out=core/src/main/java -I../src \
../src/google/protobuf/descriptor.proto
3) Compile the code in src/main/java using whatever means you prefer.
3) Compile the code in core/src/main/java using whatever means you prefer.
4) Install the classes wherever you prefer.
Usage
=====
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 compatbility
are guaranteed for minor version releases if the user follows the guideline
described in this section.
* Protobuf major version releases may also be backwards-compatbile 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
compatiblity 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: