THRIFT-5570: update java lib document about gradle usage (#2583)

* update java doc about gradle usage
* update .gitignore

2 files changed, 76 insertions, 27 deletions

diff --git a/lib/java/Makefile.am b/lib/java/Makefile.am
index 42514f41e..1e1ee9b09 100644
--- a/lib/java/Makefile.am
+++ b/lib/java/Makefile.am
@@ -20,13 +20,13 @@
 export CLASSPATH
 
 all-local:
-	gradle $(GRADLE_OPTS) assemble \
+	$(GRADLE) $(GRADLE_OPTS) assemble \
 		-Prelease=true \
 		-Pthrift.version=$(PACKAGE_VERSION) \
 		--console=plain
 
 install-exec-hook:
-	gradle $(GRADLE_OPTS) install \
+	$(GRADLE) $(GRADLE_OPTS) install \
 		-Prelease=true \
 		-Pinstall.path=$(DESTDIR)$(JAVA_PREFIX) \
 		-Pinstall.javadoc.path=$(DESTDIR)$(docdir)/java \
@@ -34,24 +34,24 @@ install-exec-hook:
 		--console=plain
 
 clean-local:
-	gradle $(GRADLE_OPTS) clean --console=plain
+	$(GRADLE) $(GRADLE_OPTS) clean --console=plain
 
 precross: $(THRIFT)
-	gradle $(GRADLE_OPTS) shadowJar \
+	$(GRADLE) $(GRADLE_OPTS) shadowJar \
 		-Prelease=true \
 		-Pthrift.version=$(PACKAGE_VERSION) \
 		-Pthrift.compiler=$(THRIFT) \
 		--console=plain
 
 check-local: $(THRIFT)
-	gradle $(GRADLE_OPTS) test \
+	$(GRADLE) $(GRADLE_OPTS) test \
 		-Prelease=true \
 		-Pthrift.version=$(PACKAGE_VERSION) \
 		-Pthrift.compiler=$(THRIFT) \
 		--console=plain
 
 maven-publish:
-	gradle $(GRADLE_OPTS) uploadArchives \
+	$(GRADLE) $(GRADLE_OPTS) uploadArchives \
 		-Prelease=true \
 		-Pthrift.version=$(PACKAGE_VERSION) \
 		--console=plain
diff --git a/lib/java/README.md b/lib/java/README.md
index f18f7dd61..214ac90b8 100644
--- a/lib/java/README.md
+++ b/lib/java/README.md
@@ -42,11 +42,41 @@ The Thrift Java source is not build using the GNU tools, but rather uses
 the Gradle build system, which tends to be predominant amongst Java
 developers.
 
+Currently we use gradle 6.9.2 to build the Thrift Java source. The usual way to setup gradle
+project is to include the gradle-wrapper.jar in the project and then run the gradle wrapper to
+bootstrap setting up gradle binaries. However to avoid putting binary files into the source tree we
+have ignored the gradle wrapper files. You are expected to install it manually, as described in
+the [gradle documentation](https://docs.gradle.org/current/userguide/installation.html), or
+following this step (which is also done in the travis CI docker images):
+
+```bash
+export GRADLE_VERSION="6.9.2"
+# install dependencies
+apt-get install -y --no-install-recommends openjdk-11-jdk-headless wget unzip
+# download gradle distribution
+wget https://services.gradle.org/distributions/gradle-$GRADLE_VERSION-bin.zip -q -O /tmp/gradle-$GRADLE_VERSION-bin.zip
+# check binary integrity
+echo "8b356fd8702d5ffa2e066ed0be45a023a779bba4dd1a68fd11bc2a6bdc981e8f  /tmp/gradle-$GRADLE_VERSION-bin.zip" | sha256sum -c -
+# unzip and install
+unzip -d /tmp /tmp/gradle-$GRADLE_VERSION-bin.zip
+mv /tmp/gradle-$GRADLE_VERSION /usr/local/gradle
+ln -s /usr/local/gradle/bin/gradle /usr/local/bin
+```
+
+After the above step, `gradle` binary will be available in `/usr/local/bin/`. You can further choose
+to locally create the gradle wrapper (even if they are ignored) using:
+
+```bash
+gradle wrapper --gradle-version $GRADLE_VERSION
+```
+
 To compile the Java Thrift libraries, simply do the following:
 
-    gradle
+```bash
+gradle
+```
 
-Yep, that's easy. Look for libthrift-<version>.jar in the build/libs directory.
+Yep, that's easy. Look for `libthrift-<version>.jar` in the build/libs directory.
 
 The default build will run the unit tests which expect a usable
 Thrift compiler to exist on the system. You have two choices for
@@ -65,12 +95,16 @@ that.
 
 To just build the library without running unit tests you simply do this.
 
-    gradle assemble
+```bash
+gradle assemble
+```
 
 To install the library in the local Maven repository location
 where other Maven or Gradle builds can reference it simply do this.
 
-    gradle install
+```bash
+gradle install
+```
 
 The library will be placed in your home directory under .m2/repository
 
@@ -80,12 +114,16 @@ classpath, or install if in your default system classpath of choice.
 
 Build Thrift behind a proxy:
 
-    gradle -Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=8080 -Dhttp.proxyUser=thriftuser -Dhttp.proxyPassword=topsecret
 
-or via
+```bash
+gradle -Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=8080 -Dhttp.proxyUser=thriftuser -Dhttp.proxyPassword=topsecret
+```
 
-    ./configure --with-java GRADLE_OPTS='-Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=8080 -Dhttp.proxyUser=thriftuser -Dhttp.proxyPassword=topsecret'
+or via
 
+```bash
+./configure --with-java GRADLE_OPTS='-Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=8080 -Dhttp.proxyUser=thriftuser -Dhttp.proxyPassword=topsecret'
+```
 
 Unit Test HTML Reports
 ======================
@@ -107,8 +145,9 @@ under the location build/reports/clover/clover.pdf.
 
 The following command will build, unit test, and generate Clover reports:
 
-    gradle -PcloverEnabled=true
-
+```bash
+gradle -PcloverEnabled=true
+```
 
 Publishing Maven Artifacts to Maven Central
 ===========================================
@@ -119,8 +158,10 @@ version number. The Gradle build will receive the correct value for the build.
 The same applies to the CMake build, the value from the configure.ac file will
 be used if you execute these commands:
 
-    make maven-publish   -- This is for an Automake Linux build
-    make MavenPublish    -- This is for a CMake generated build
+```bash
+make maven-publish   -- This is for an Automake Linux build
+make MavenPublish    -- This is for a CMake generated build
+```
 
 The uploadArchives task in Gradle is preconfigured with all necessary details
 to sign and publish the artifacts from the build to the Apache Maven staging
@@ -129,14 +170,16 @@ authenticate to the repository and sign the artifacts. The preferred approach
 is to create or edit the ~/.gradle/gradle.properties file and add the following
 properties to it.
 
-    # Signing key information for artifacts PGP signature (values are examples)
-    signing.keyId=24875D73
-    signing.password=secret
-    signing.secretKeyRingFile=/Users/me/.gnupg/secring.gpg
+```properties
+# Signing key information for artifacts PGP signature (values are examples)
+signing.keyId=24875D73
+signing.password=secret
+signing.secretKeyRingFile=/Users/me/.gnupg/secring.gpg
 
-    # Apache Maven staging repository user credentials
-    mavenUser=meMyselfAndI
-    mavenPassword=MySuperAwesomeSecretPassword
+# Apache Maven staging repository user credentials
+mavenUser=meMyselfAndI
+mavenPassword=MySuperAwesomeSecretPassword
+```
 
 NOTE: If you do not have a secring.gpg file, see the
 [gradle signing docs](https://docs.gradle.org/current/userguide/signing_plugin.html)
@@ -146,18 +189,24 @@ It is also possible to manually publish using the Gradle build directly.
 With the key information and credentials in place the following will generate
 if needed the build artifacts and proceed to publish the results.
 
-    gradle -Prelease=true uploadArchives
+```bash
+gradle -Prelease=true uploadArchives
+```
 
 It is also possible to override the target repository for the Maven Publication
 by using a Gradle property, for example you can publish signed JAR files to your
 company internal server if you add this to the command line or in the
 ~/.gradle/gradle.properties file. The URL below assumes a Nexus Repository.
 
-    maven-repository-url=https://my.company.com/service/local/staging/deploy/maven2
+```properties
+maven-repository-url=https://my.company.com/service/local/staging/deploy/maven2
+```
 
 Or the same on the command line:
 
-    gradle -Pmaven-repository-url=https://my.company.com/service/local/staging/deploy/maven2 -Prelease=true -Pthrift.version=0.11.0 uploadArchives
+```bash
+gradle -Pmaven-repository-url=https://my.company.com/service/local/staging/deploy/maven2 -Prelease=true -Pthrift.version=0.11.0 uploadArchives
+```
 
 
 Dependencies