Merge pull request #4504 from xfxyjwf/lite

Cleanup + documentation for Java Lite runtime.

Makefile.am

@@ -370,9 +370,7 @@ java_EXTRA_DIST=
   java/core/src/test/proto/com/google/protobuf/test_check_utf8_size.proto          \
   java/core/src/test/proto/com/google/protobuf/test_custom_options.proto           \
   java/core/src/test/proto/com/google/protobuf/test_extra_interfaces.proto         \
-  java/lite/generate-sources-build.xml                                             \
-  java/lite/generate-test-sources-build.xml                                        \
-  java/lite/pom.xml                                                                \
+  java/lite.md                                                                     \
   java/pom.xml                                                                     \
   java/util/pom.xml                                                                \
   java/util/src/main/java/com/google/protobuf/util/Durations.java                  \

java/README.md

@@ -1,17 +1,65 @@
-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,0 +1,50 @@
+# 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

@@ -1,20 +0,0 @@
-<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

@@ -1,43 +0,0 @@
-<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

@@ -1,185 +0,0 @@
-<?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

@@ -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

@@ -223,6 +223,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;
 }