2007-03-06 00:06:27 +00:00
|
|
|
Thrift Java Software Library
|
|
|
|
|
|
2009-04-08 00:19:37 +00:00
|
|
|
License
|
|
|
|
|
=======
|
|
|
|
|
|
|
|
|
|
Licensed to the Apache Software Foundation (ASF) under one
|
|
|
|
|
or more contributor license agreements. See the NOTICE file
|
|
|
|
|
distributed with this work for additional information
|
|
|
|
|
regarding copyright ownership. The ASF licenses this file
|
|
|
|
|
to you under the Apache License, Version 2.0 (the
|
|
|
|
|
"License"); you may not use this file except in compliance
|
|
|
|
|
with the License. You may obtain a copy of the License at
|
|
|
|
|
|
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
|
|
|
|
|
|
Unless required by applicable law or agreed to in writing,
|
|
|
|
|
software distributed under the License is distributed on an
|
|
|
|
|
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
|
|
|
|
|
KIND, either express or implied. See the License for the
|
|
|
|
|
specific language governing permissions and limitations
|
|
|
|
|
under the License.
|
2007-03-06 00:06:27 +00:00
|
|
|
|
2018-01-24 10:30:13 -05:00
|
|
|
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
|
|
|
|
|
==================================================
|
2007-03-06 00:06:27 +00:00
|
|
|
|
|
|
|
|
The Thrift Java source is not build using the GNU tools, but rather uses
|
2018-01-24 10:30:13 -05:00
|
|
|
the Gradle build system, which tends to be predominant amongst Java
|
2007-03-06 00:06:27 +00:00
|
|
|
developers.
|
|
|
|
|
|
2024-09-17 20:42:24 -04:00
|
|
|
Currently we use gradle 8 to build the Thrift Java source. The usual way to setup gradle
|
2022-05-06 12:42:18 +08:00
|
|
|
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
|
2023-10-19 08:37:49 +08:00
|
|
|
export GRADLE_VERSION="8.4"
|
2022-05-06 12:42:18 +08:00
|
|
|
# install dependencies
|
2022-10-14 13:16:18 +08:00
|
|
|
apt-get install -y --no-install-recommends openjdk-17-jdk-headless wget unzip
|
2022-05-06 12:42:18 +08:00
|
|
|
# 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
|
2023-10-19 08:37:49 +08:00
|
|
|
echo "3e1af3ae886920c3ac87f7a91f816c0c7c436f276a6eefdb3da152100fef72ae /tmp/gradle-$GRADLE_VERSION-bin.zip" | sha256sum -c -
|
2022-05-06 12:42:18 +08:00
|
|
|
# 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
|
|
|
|
|
```
|
|
|
|
|
|
2007-03-06 00:06:27 +00:00
|
|
|
To compile the Java Thrift libraries, simply do the following:
|
|
|
|
|
|
2022-05-06 12:42:18 +08:00
|
|
|
```bash
|
|
|
|
|
gradle
|
|
|
|
|
```
|
2018-01-24 10:30:13 -05:00
|
|
|
|
2022-05-06 12:42:18 +08:00
|
|
|
Yep, that's easy. Look for `libthrift-<version>.jar` in the build/libs directory.
|
2018-01-24 10:30:13 -05:00
|
|
|
|
|
|
|
|
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
|
2007-03-06 00:06:27 +00:00
|
|
|
|
2018-01-24 10:30:13 -05:00
|
|
|
To just build the library without running unit tests you simply do this.
|
|
|
|
|
|
2022-05-06 12:42:18 +08:00
|
|
|
```bash
|
|
|
|
|
gradle assemble
|
|
|
|
|
```
|
2018-01-24 10:30:13 -05:00
|
|
|
|
|
|
|
|
To install the library in the local Maven repository location
|
|
|
|
|
where other Maven or Gradle builds can reference it simply do this.
|
|
|
|
|
|
2022-05-06 12:42:18 +08:00
|
|
|
```bash
|
2022-05-12 00:20:37 +08:00
|
|
|
gradle publishToMavenLocal
|
2022-05-06 12:42:18 +08:00
|
|
|
```
|
2018-01-24 10:30:13 -05:00
|
|
|
|
|
|
|
|
The library will be placed in your home directory under .m2/repository
|
2007-03-06 00:06:27 +00:00
|
|
|
|
|
|
|
|
To include Thrift in your applications simply add libthrift.jar to your
|
|
|
|
|
classpath, or install if in your default system classpath of choice.
|
|
|
|
|
|
2012-01-24 19:35:09 +00:00
|
|
|
|
|
|
|
|
Build Thrift behind a proxy:
|
|
|
|
|
|
|
|
|
|
|
2022-05-06 12:42:18 +08:00
|
|
|
```bash
|
|
|
|
|
gradle -Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=8080 -Dhttp.proxyUser=thriftuser -Dhttp.proxyPassword=topsecret
|
|
|
|
|
```
|
2012-01-24 19:35:09 +00:00
|
|
|
|
2022-05-06 12:42:18 +08:00
|
|
|
or via
|
2018-01-24 10:30:13 -05:00
|
|
|
|
2022-05-06 12:42:18 +08:00
|
|
|
```bash
|
|
|
|
|
./configure --with-java GRADLE_OPTS='-Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=8080 -Dhttp.proxyUser=thriftuser -Dhttp.proxyPassword=topsecret'
|
|
|
|
|
```
|
2018-01-24 10:30:13 -05:00
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
2022-05-06 12:42:18 +08:00
|
|
|
```bash
|
|
|
|
|
gradle -PcloverEnabled=true
|
|
|
|
|
```
|
2018-01-24 10:30:13 -05:00
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
2022-05-06 12:42:18 +08:00
|
|
|
```bash
|
|
|
|
|
make maven-publish -- This is for an Automake Linux build
|
|
|
|
|
make MavenPublish -- This is for a CMake generated build
|
|
|
|
|
```
|
2018-01-24 10:30:13 -05:00
|
|
|
|
2022-05-12 00:20:37 +08:00
|
|
|
The `publish` task in Gradle is preconfigured with all necessary details
|
2018-01-24 10:30:13 -05:00
|
|
|
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.
|
|
|
|
|
|
2022-05-06 12:42:18 +08:00
|
|
|
```properties
|
|
|
|
|
# Signing key information for artifacts PGP signature (values are examples)
|
|
|
|
|
signing.keyId=24875D73
|
|
|
|
|
signing.password=secret
|
|
|
|
|
signing.secretKeyRingFile=/Users/me/.gnupg/secring.gpg
|
2018-01-24 10:30:13 -05:00
|
|
|
|
2022-05-06 12:42:18 +08:00
|
|
|
# Apache Maven staging repository user credentials
|
|
|
|
|
mavenUser=meMyselfAndI
|
|
|
|
|
mavenPassword=MySuperAwesomeSecretPassword
|
|
|
|
|
```
|
2018-01-24 10:30:13 -05:00
|
|
|
|
2019-01-22 09:22:04 -05:00
|
|
|
NOTE: If you do not have a secring.gpg file, see the
|
|
|
|
|
[gradle signing docs](https://docs.gradle.org/current/userguide/signing_plugin.html)
|
|
|
|
|
for instructions on how to generate it.
|
|
|
|
|
|
2018-01-24 10:30:13 -05:00
|
|
|
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.
|
|
|
|
|
|
2022-05-06 12:42:18 +08:00
|
|
|
```bash
|
2022-05-12 00:20:37 +08:00
|
|
|
gradle -Prelease=true publish
|
2022-05-06 12:42:18 +08:00
|
|
|
```
|
2018-01-24 10:30:13 -05:00
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
2022-05-06 12:42:18 +08:00
|
|
|
```properties
|
|
|
|
|
maven-repository-url=https://my.company.com/service/local/staging/deploy/maven2
|
|
|
|
|
```
|
2018-01-24 10:30:13 -05:00
|
|
|
|
|
|
|
|
Or the same on the command line:
|
|
|
|
|
|
2022-05-06 12:42:18 +08:00
|
|
|
```bash
|
2022-05-12 00:20:37 +08:00
|
|
|
gradle -Pmaven-repository-url=https://my.company.com/service/local/staging/deploy/maven2 -Prelease=true -Pthrift.version=0.11.0 publish
|
2022-05-06 12:42:18 +08:00
|
|
|
```
|
2012-01-24 19:35:09 +00:00
|
|
|
|
|
|
|
|
|
2007-03-06 00:06:27 +00:00
|
|
|
Dependencies
|
|
|
|
|
============
|
|
|
|
|
|
2018-01-24 10:30:13 -05:00
|
|
|
Gradle
|
|
|
|
|
http://gradle.org/
|
2018-12-31 10:58:19 -05:00
|
|
|
|
|
|
|
|
# Breaking Changes
|
|
|
|
|
|
2019-07-08 06:49:15 -04:00
|
|
|
## 0.13.0
|
2019-01-06 15:08:58 -05:00
|
|
|
|
2019-03-11 14:14:05 -07:00
|
|
|
* The signature of the 'process' method in TAsyncProcessor and TProcessor has
|
2019-07-08 06:49:15 -04:00
|
|
|
changed to remove the boolean return type and instead rely on Exceptions.
|
2019-01-06 15:08:58 -05:00
|
|
|
|
2019-03-11 14:14:05 -07:00
|
|
|
* Per THRIFT-4805, TSaslTransportException has been removed. The same condition
|
|
|
|
|
is now covered by TTansportException, where `TTransportException.getType() == END_OF_FILE`.
|
2022-04-19 04:18:58 +02:00
|
|
|
|
2018-12-31 10:58:19 -05:00
|
|
|
## 0.12.0
|
|
|
|
|
|
|
|
|
|
The access modifier of the AutoExpandingBuffer class has been changed from
|
|
|
|
|
public to default (package) and will no longer be accessible by third-party
|
|
|
|
|
libraries.
|
|
|
|
|
|
2019-01-01 16:35:04 -05:00
|
|
|
The access modifier of the ShortStack class has been changed from
|
|
|
|
|
public to default (package) and will no longer be accessible by third-party
|
|
|
|
|
libraries.
|
|
|
|
|
|
