Skip to content

P
protobuf
Commit 7d55040e authored by Feng Xiao's avatar Feng Xiao
Browse files
Options

Cleanup + documentation for Java Lite runtime.

parent 320d56c8
Hide whitespace changes
Inline Side-by-side
Showing with 121 additions and 271 deletions
java/README.md
View file @ 7d55040e
Protocol Buffers - Google's data interchange format
===================================================
[![Build Status](https://travis-ci.org/google/protobuf.svg?branch=master)](https://travis-ci.org/google/protobuf)
# Protocol Buffers - Google's data interchange format
Copyright 2008 Google Inc.
This directory contains the Java Protocol Buffers runtime library.
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](../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. If you are using Maven, use the following:
```xml
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protobuf-java</artifactId>
<version>3.5.1</version>
</dependency>
```
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:
```xml
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protobuf-java-util</artifactId>
<version>3.5.1</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](lite.md).
### 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](../examples/BUILD) to learn
how to use them.
## Build from Source
Installation - With Maven
=========================
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 folllow the instructions
below to build protobuf from source code.
The Protocol Buffers build is managed using Maven. If you would
rather build without Maven, see below.
### Build from Source - With Maven
1) Install Apache Maven if you don't have it:
......@@ -45,20 +93,15 @@ rather build without Maven, see below.
The .jar will be placed in the "target" directory.
The above instructions will install 3 maven artifacts:
The above instructions will install 2 maven artifacts:
* 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
============================
### Build from Source - Without Maven
If you would rather not install Maven to build the library, you may
follow these instructions instead. Note that these instructions skip
......@@ -83,8 +126,7 @@ library (without the util package).
4) Install the classes wherever you prefer.
Compatibility Notice
====================
## 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
......@@ -118,8 +160,7 @@ Compatibility Notice
* Protobuf LITE runtime APIs are not stable yet. They are subject to change even
in minor version releases.
Documentation
=============
## Documentation
The complete documentation for Protocol Buffers is available via the
web at:
......
java/lite.md 0 → 100644
View file @ 7d55040e
# Protocol Buffers - Google's data interchange format
Copyright 2008 Google Inc.
https://developers.google.com/protocol-buffers/
## Use Protobuf Java Lite Runtime
Protobuf Java Lite runtime is separated from the main Java runtime because
it's designed/implemented with different constraints. In particular, Java
Lite runtime has a much smaller code size which makes it more suitable to
be used on Android.
To use Java Lite runtime, you need to install protoc and the protoc plugin for
Java Lite runtime. You can obtain protoc following the instructions in the
toplevel [README.md](../README.md) file. For the protoc plugin, you can
download it from maven:
https://repo1.maven.org/maven2/com/google/protobuf/protoc-gen-javalite/
Choose the version that works on your platform (e.g., on windows you can
download `protoc-gen-javalite-3.0.0-windows-x86_32.exe`), rename it to
protoc-gen-javalite (or protoc-gen-javalite.exe on windows) and place it
in a directory where it can be find in PATH.
Once you have the protoc and protoc plugin, you can generate Java Lite code
for your .proto files:
$ protoc --javalite_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. If you are using Maven, use the following:
```xml
<dependency>
<groupId>com.google.protobuf</groupId>
<artifactId>protobuf-lite</artifactId>
<version>3.0.1</version>
</dependency>
```
Make sure the version number of the runtime matches (or is newer than) the
version number of the protoc plugin. The version number of the protoc doesn't
matter and any version >= 3.0.0 should work.
### Use Protobuf Java Lite Runtime with Bazel
Bazel has native build rules to work with protobuf. For Java Lite runtime,
you can use the `java_lite_proto_library` rule. Check out [our build files
examples](../examples/BUILD) to learn how to use it.
java/lite/generate-sources-build.xml deleted 100644 → 0
View file @ 320d56c8
<project name="generate-sources">
<echo message="Running protoc ..."/>
<mkdir dir="${generated.sources.lite.dir}"/>
<exec executable="${protoc}">
<arg value="--java_out=lite:${generated.sources.lite.dir}"/>
<arg value="--proto_path=${protobuf.source.dir}"/>
<arg value="${protobuf.source.dir}/google/protobuf/any.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/api.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/descriptor.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/duration.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/empty.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/field_mask.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/source_context.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/struct.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/timestamp.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/type.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/wrappers.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/compiler/plugin.proto"/>
</exec>
</project>
java/lite/generate-test-sources-build.xml deleted 100644 → 0
View file @ 320d56c8
<project name="generate-test-sources">
<mkdir dir="${generated.testsources.lite.dir}"/>
<exec executable="${protoc}">
<arg value="--java_out=lite:${generated.testsources.lite.dir}"/>
<arg value="--proto_path=${protobuf.source.dir}"/>
<arg value="--proto_path=${test.proto.dir}"/>
<arg value="${protobuf.source.dir}/google/protobuf/unittest.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/unittest_import.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/unittest_import_public.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/unittest_mset.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/unittest_mset_wire_format.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/unittest_optimize_for.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/unittest_custom_options.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/unittest_lite.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/unittest_import_lite.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/unittest_import_public_lite.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/unittest_lite_imports_nonlite.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/unittest_enormous_descriptor.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/unittest_no_generic_services.proto"/>
<arg value="${protobuf.source.dir}/google/protobuf/unittest_well_known_types.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/lazy_fields_lite.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/lite_equals_and_hash.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/multiple_files_test.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/nested_builders_test.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/nested_extension.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/nested_extension_lite.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/non_nested_extension.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/non_nested_extension_lite.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/outer_class_name_test.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/outer_class_name_test2.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/outer_class_name_test3.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/test_bad_identifiers.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/test_check_utf8.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/test_check_utf8_size.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/test_custom_options.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/any_test.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/field_presence_test.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/map_for_proto2_lite_test.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/map_for_proto2_test.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/map_test.proto"/>
<arg value="${test.proto.dir}/com/google/protobuf/map_initialization_order_test.proto"/>
</exec>
</project>
java/lite/pom.xml deleted 100644 → 0
View file @ 320d56c8
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>com.google.protobuf</groupId>
<artifactId>protobuf-parent</artifactId>
<version>3.0.0</version>
</parent>
<artifactId>protobuf-lite</artifactId>
<packaging>bundle</packaging>
<name>Protocol Buffers [Lite]</name>
<description>A trimmed-down version of the Protocol Buffers library.</description>
<dependencies>
<dependency>
<groupId>junit</groupId>
<artifactId>junit</artifactId>
</dependency>
<dependency>
<groupId>org.easymock</groupId>
<artifactId>easymock</artifactId>
</dependency>
<dependency>
<groupId>org.easymock</groupId>
<artifactId>easymockclassextension</artifactId>
</dependency>
</dependencies>
<properties>
<core.root>../core</core.root>
<test.proto.dir>${core.root}/src/test/proto</test.proto.dir>
</properties>
<build>
<sourceDirectory>${core.root}/src/main/java</sourceDirectory>
<testSourceDirectory>${core.root}/src/test/java</testSourceDirectory>
<plugins>
<!-- Use Antrun plugin to generate sources with protoc -->
<plugin>
<artifactId>maven-antrun-plugin</artifactId>
<executions>
<!-- Generate core protos -->
<execution>
<id>generate-sources</id>
<phase>generate-sources</phase>
<configuration>
<target>
<ant antfile="generate-sources-build.xml"/>
</target>
</configuration>
<goals>
<goal>run</goal>
</goals>
</execution>
<!-- Generate the test protos -->
<execution>
<id>generate-test-sources</id>
<phase>generate-test-sources</phase>
<configuration>
<target>
<ant antfile="generate-test-sources-build.xml"/>
</target>
</configuration>
<goals>
<goal>run</goal>
</goals>
</execution>
</executions>
</plugin>
<!-- Only compile a subset of the files -->
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>build-helper-maven-plugin</artifactId>
<executions>
<execution>
<id>add-generated-sources</id>
<phase>generate-sources</phase>
<goals>
<goal>add-source</goal>
</goals>
<configuration>
<sources>
<source>${generated.sources.lite.dir}</source>
</sources>
</configuration>
</execution>
<execution>
<id>add-generated-test-sources</id>
<phase>generate-test-sources</phase>
<goals>
<goal>add-test-source</goal>
</goals>
<configuration>
<sources>
<source>${generated.testsources.lite.dir}</source>
</sources>
</configuration>
</execution>
</executions>
</plugin>
<plugin>
<artifactId>maven-compiler-plugin</artifactId>
<configuration>
<includes>
<include>**/AbstractMessageLite.java</include>
<include>**/AbstractParser.java</include>
<include>**/AbstractProtobufList.java</include>
<include>**/BooleanArrayList.java</include>
<include>**/ByteString.java</include>
<include>**/CodedInputStream.java</include>
<include>**/CodedOutputStream.java</include>
<include>**/DoubleArrayList.java</include>
<include>**/ExtensionLite.java</include>
<include>**/ExtensionRegistryLite.java</include>
<include>**/FieldSet.java</include>
<include>**/FloatArrayList.java</include>
<include>**/GeneratedMessageLite.java</include>
<include>**/IntArrayList.java</include>
<include>**/Internal.java</include>
<include>**/InvalidProtocolBufferException.java</include>
<include>**/LazyFieldLite.java</include>
<include>**/LazyStringArrayList.java</include>
<include>**/LazyStringList.java</include>
<include>**/LongArrayList.java</include>
<include>**/MapEntryLite.java</include>
<include>**/MapFieldLite.java</include>
<include>**/MessageLite.java</include>
<include>**/MessageLiteOrBuilder.java</include>
<include>**/MessageLiteToString.java</include>
<include>**/MutabilityOracle.java</include>
<include>**/NioByteString.java</include>
<include>**/Parser.java</include>
<include>**/PrimitiveNonBoxingCollection.java</include>
<include>**/ProtobufArrayList.java</include>
<include>**/ProtocolStringList.java</include>
<include>**/RopeByteString.java</include>
<include>**/SmallSortedMap.java</include>
<include>**/TextFormatEscaper.java</include>
<include>**/UninitializedMessageException.java</include>
<include>**/UnknownFieldSetLite.java</include>
<include>**/UnmodifiableLazyStringList.java</include>
<include>**/UnsafeByteOperations.java</include>
<include>**/Utf8.java</include>
<include>**/WireFormat.java</include>
</includes>
<testIncludes>
<testInclude>**/*Lite.java</testInclude>
<testInclude>**/BooleanArrayListTest.java</testInclude>
<testInclude>**/DoubleArrayListTest.java</testInclude>
<testInclude>**/FloatArrayListTest.java</testInclude>
<testInclude>**/IntArrayListTest.java</testInclude>
<testInclude>**/LazyMessageLiteTest.java</testInclude>
<testInclude>**/LiteTest.java</testInclude>
<testInclude>**/LongArrayListTest.java</testInclude>
<testInclude>**/NioByteStringTest.java</testInclude>
<testInclude>**/ProtobufArrayListTest.java</testInclude>
<testInclude>**/UnknownFieldSetLiteTest.java</testInclude>
</testIncludes>
</configuration>
</plugin>
<!-- OSGI bundle configuration -->
<plugin>
<groupId>org.apache.felix</groupId>
<artifactId>maven-bundle-plugin</artifactId>
<extensions>true</extensions>
<configuration>
<instructions>
<Bundle-DocURL>https://developers.google.com/protocol-buffers/</Bundle-DocURL>
<Bundle-SymbolicName>com.google.protobuf</Bundle-SymbolicName>
<Export-Package>com.google.${project.artifactId};version=${project.version}</Export-Package>
</instructions>
</configuration>
</plugin>
</plugins>
</build>
</project>
java/pom.xml
View file @ 7d55040e
......@@ -33,8 +33,6 @@
<test.proto.dir>src/test/proto</test.proto.dir>
<generated.sources.dir>${project.build.directory}/generated-sources</generated.sources.dir>
<generated.testsources.dir>${project.build.directory}/generated-test-sources</generated.testsources.dir>
<generated.sources.lite.dir>${project.build.directory}/generated-sources-lite</generated.sources.lite.dir>
<generated.testsources.lite.dir>${project.build.directory}/generated-test-sources-lite</generated.testsources.lite.dir>
</properties>
<licenses>
......@@ -208,7 +206,6 @@
<modules>
<module>core</module>
<!-- <module>lite</module> -->
<module>util</module>
</modules>
......
src/google/protobuf/compiler/java/java_file.cc
View file @ 7d55040e
......@@ -225,6 +225,16 @@ bool FileGenerator::Validate(string* error) {
"option to specify a different outer class name for the .proto file.");
return false;
}
// Print a warning if optimize_for = LITE_RUNTIME is used.
if (file_->options().optimize_for() == FileOptions::LITE_RUNTIME) {
GOOGLE_LOG(WARNING)
<< "The optimize_for = LITE_RUNTIME option is no longer supported by "
<< "protobuf Java code generator and may generate broken code. It "
<< "will be ignored by protoc in the future and protoc will always "
<< "generate full runtime code for Java. To use Java Lite runtime, "
<< "users should use the Java Lite plugin instead. See:\n"
<< " https://github.com/google/protobuf/blob/master/java/lite.md";
}
return true;
}
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment