THRIFT-(1418|1507|3983|4120|4178|4259|4294): Multiple issues
Client: java
THRIFT-4294: Java Configure Fails for Ant >= 1.10
THRIFT-4259: Thrift does not compile due to Ant Maven task errors
THRIFT-4178: Java libraries missing from package when using cmake
THRIFT-3983: libthrift is deployed on central with pom packaging
instead of jar
THRIFT-1507: Maven can't download resource from central when behind
a proxy and won't use local repository
THRIFT-1418: Compiling Thrift from source: Class
org.apache.tools.ant.taskdefs.ConditionTask doesn't
support the nested "typefound" element
Refactor CMake install hook to allow using "sudo make install/fast"
which avoids the THRIFT-1507 and THRIFT-1418 issues.
New Gradle based build system for Thrift Java Library
* Add Gradle 4.4.1 Wrapper artifacts to enable builds
Using the Gradle Wrapper helps normalize the builds on all platforms
so we use a consistent build tool independent of package managers.
The Gradle build logic was partitioned into multiple specific
scripts to simplify understanding and maintenance of the build.
This is now hooked into CMake and Autoconf processing steps
and can build/test/publish to Maven. The README.md was updated
to illustrate the new build options and add some documentation
on the requirements for Maven publication.
Cleaned up the CMake files to reduce reliance on file globbing
which is known to cause confusion when multiple users contribute.
* Fix two minor issues in Javadoc and unit test
Return values were undeclared in Javadoc
Test was asserting on the wrong test object instance
* Create simple runner scripts for cross-check
Using Gradle as a java execution wrapper is too heavy.
I simplified the test client/server execution by using a
three generated scripts in the build directory direcly
callable by the cross-check test harness.
* Cleanup the remaining Ant build scripts
Pulled the Maven Ant task properties out of the Java build
since they are no longer used there.
Deleted the no longer used build.xml and build.properties
files from the Java build.
Made each Ant build own the Maven Ant task details in their
build.properties file.
* Fix the build issue with Java SSL in the ubuntu-trusty container
The latest Trusty JDK7 builds seem to have encountered this issue
because the OpenJDK removed the SunEC algorithms.
* Update the developer info as requested in review
Use the generic Apache Thrift developer list for contact information
* Add Clover Code coverage for easy access by developers
Clover plugin for Gradle was applied and configured which enables
code coverage reports to be available on demand via a command line
option. The documentation in the README.md was enhanced to give
the details of this change and how to take advantage of it.
diff --git a/lib/java/README.md b/lib/java/README.md
index 66bcfa5..1e4aed2 100644
--- a/lib/java/README.md
+++ b/lib/java/README.md
@@ -20,18 +20,59 @@
specific language governing permissions and limitations
under the License.
-Using Thrift with Java
-======================
+Building and installing from source
+===================================
+
+When using a CMake build from the source distribution on Linux the
+easiest way to build and install is this simple command line:
+
+ make all && sudo make install/fast
+
+It is important to use the install/fast option to eliminate
+the automatic rebuild by dependency that causes issues because
+the build tooling is designed to work with cached files in the
+user home directory during the build process. Instead this builds
+the code in the expected local build tree and then uses CMake
+install code to copy to the target destination.
+
+Building Thrift with Gradle without CMake/Autoconf
+==================================================
The Thrift Java source is not build using the GNU tools, but rather uses
-the Apache Ant build system, which tends to be predominant amongst Java
+the Gradle build system, which tends to be predominant amongst Java
developers.
To compile the Java Thrift libraries, simply do the following:
- ant
+ ./gradlew
-Yep, that's easy. Look for libthrift.jar in the base 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
+that.
+
+* Build the Thrift executable from source at the default
+ location in the source tree. The project is configured
+ to look for it there.
+* Install the published binary distribution to have Thrift
+ executable in a known location and add the path to the
+ ~/.gradle/gradle.properties file using the property name
+ "thrift.compiler". For example this would set the path in
+ a Windows box if Thrift was installed under C:\Thrift
+
+ thrift.compiler=C:/Thrift/thrift.exe
+
+To just build the library without running unit tests you simply do this.
+
+ ./gradlew assemble
+
+To install the library in the local Maven repository location
+where other Maven or Gradle builds can reference it simply do this.
+
+ ./gradlew install
+
+The library will be placed in your home directory under .m2/repository
To include Thrift in your applications simply add libthrift.jar to your
classpath, or install if in your default system classpath of choice.
@@ -39,15 +80,84 @@
Build Thrift behind a proxy:
- ant -Dproxy.enabled=1 -Dproxy.host=myproxyhost -Dproxy.user=thriftuser -Dproxy.pass=topsecret
+ ./gradlew -Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=8080 -Dhttp.proxyUser=thriftuser -Dhttp.proxyPassword=topsecret
or via
- ./configure --with-java ANT_FLAGS='-Dproxy.enabled=1 -Dproxy.host=myproxyhost -Dproxy.user=thriftuser -Dproxy.pass=topsecret'
+ ./configure --with-java GRADLE_OPTS='-Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=8080 -Dhttp.proxyUser=thriftuser -Dhttp.proxyPassword=topsecret'
+
+
+Unit Test HTML Reports
+======================
+
+The build will automatically generate an HTML Unit Test report. This can be found
+under build/reports/tests/test/index.html. It can be viewed with a browser
+directly from that location.
+
+
+Clover Code Coverage for Thrift
+===============================
+
+The build will optionally generate Clover Code coverage if the Gradle property
+`cloverEnabled=true` is set in ~/.gradle/gradle.properties or on the command line
+via `-PcloverEnabled=true`. The generated report can be found under the location
+build/reports/clover/html/index.html. It can be viewed with a browser
+directly from that location. Additionally, a PDF report is generated and is found
+under the location build/reports/clover/clover.pdf.
+
+The following command will build, unit test, and generate Clover reports:
+
+ ./gradlew -PcloverEnabled=true
+
+
+Publishing Maven Artifacts to Maven Central
+===========================================
+
+The Automake build generates a Makefile that provides the correct parameters
+when you run the build provided the configure.ac has been set with the correct
+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
+
+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
+repository. The task requires the following externally provided properties to
+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
+
+ # Apache Maven staging repository user credentials
+ mavenUser=meMyselfAndI
+ mavenPassword=MySuperAwesomeSecretPassword
+
+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.
+
+ ./gradlew -Prelease=true -Pthrift.version=0.11.0 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
+
+Or the same on the command line:
+
+ ./gradlew -Pmaven-repository-url=https://my.company.com/service/local/staging/deploy/maven2 -Prelease=true -Pthrift.version=0.11.0 uploadArchives
Dependencies
============
-Apache Ant
-http://ant.apache.org/
+Gradle
+http://gradle.org/