Cleanup + documentation for Java Lite runtime.
diff --git a/java/README.md b/java/README.md
index 0e0fba6..5e4fb8b 100644
--- a/java/README.md
+++ b/java/README.md
@@ -1,17 +1,65 @@
-Protocol Buffers - Google's data interchange format
-===================================================
-
-[](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/
-Installation - With Maven
-=========================
+## Use Java Protocol Buffers
-The Protocol Buffers build is managed using Maven. If you would
-rather build without Maven, see below.
+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
+
+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.
+
+### Build from Source - With Maven
1) Install Apache Maven if you don't have it:
@@ -45,20 +93,15 @@
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 @@
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 @@
* 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:
diff --git a/java/lite.md b/java/lite.md
new file mode 100644
index 0000000..84a45ec
--- /dev/null
+++ b/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.
diff --git a/java/lite/generate-sources-build.xml b/java/lite/generate-sources-build.xml
deleted file mode 100644
index 89c21c1..0000000
--- a/java/lite/generate-sources-build.xml
+++ /dev/null
@@ -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>
diff --git a/java/lite/generate-test-sources-build.xml b/java/lite/generate-test-sources-build.xml
deleted file mode 100644
index cdd1ee8..0000000
--- a/java/lite/generate-test-sources-build.xml
+++ /dev/null
@@ -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>
diff --git a/java/lite/pom.xml b/java/lite/pom.xml
deleted file mode 100644
index c902f81..0000000
--- a/java/lite/pom.xml
+++ /dev/null
@@ -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>
diff --git a/java/pom.xml b/java/pom.xml
index c42cae1..f228491 100644
--- a/java/pom.xml
+++ b/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>
diff --git a/src/google/protobuf/compiler/java/java_file.cc b/src/google/protobuf/compiler/java/java_file.cc
index 5ee04e5..610bc51 100644
--- a/src/google/protobuf/compiler/java/java_file.cc
+++ b/src/google/protobuf/compiler/java/java_file.cc
@@ -225,6 +225,16 @@
"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;
}
