| <!DOCTYPE html> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta content="text/html; charset=utf-8" http-equiv="Content-Type" /> |
| <meta content="en-us" http-equiv="Content-Language" /> |
| <meta name="viewport" content="width=device-width, initial-scale=1.0"> |
| |
| <link href="/static/images/favicon.ico" rel="shortcut icon" /> |
| <link href="/static/css/style.css" rel="stylesheet" type="text/css" /> |
| <link href="/static/css/codehilite.css" rel="stylesheet" type="text/css" /> |
| <link href="/static/css/bootstrap.css" media="screen, projection" rel="stylesheet" type="text/css" /> |
| <link href="/static/css/thrift.css" media="screen, projection" rel="stylesheet" type="text/css" /> |
| |
| <script src="/static/js/jquery.min.js"></script> |
| <script src="/static/js/bootstrap-dropdown.js"></script> |
| <script src="/static/js/bootstrap-tab.js"></script> |
| <script src="/static/js/thrift.js"></script> |
| |
| <title>Apache Thrift - Java library</title> |
| </head> |
| <body> |
| <div class="navbar"> |
| <div class="navbar-inner"> |
| <div class="container"> |
| <a class="brand" href="/">Apache Thrift ™</a> |
| <div class="nav-collapse"> |
| <ul class="nav pull-right"> |
| <li><a href="/download">Download</a></li> |
| <li><a href="/docs">Documentation</a></li> |
| <li><a href="/developers">Developers</a></li> |
| <li><a href="/lib">Libraries</a></li> |
| <li><a href="/tutorial">Tutorial</a></li> |
| <li><a href="/test">Test Suite</a></li> |
| <li><a href="/about">About</a></li> |
| <li class="dropdown"> |
| <a href="#" class="dropdown-toggle" data-toggle="dropdown">Apache <b class="caret"></b></a> |
| <ul class="dropdown-menu"> |
| <li><a href="http://www.apache.org/" target="_blank">Apache Home</a></li> |
| <li><a href="http://www.apache.org/licenses/" target="_blank">Apache License v2.0</a></li> |
| <li><a href="http://www.apache.org/foundation/sponsorship.html" target="_blank">Donate</a></li> |
| <li><a href="http://www.apache.org/foundation/thanks.html" target="_blank">Thanks</a></li> |
| <li><a href="http://www.apache.org/security/" target="_blank">Security</a></li> |
| </ul> |
| </li> |
| </ul> |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| <div class="container"> |
| |
| <h1 id="building-and-installing-from-source">Building and installing from source</h1> |
| |
| <p>When using a CMake build from the source distribution on Linux the |
| easiest way to build and install is this simple command line:</p> |
| |
| <pre><code>make all && sudo make install/fast |
| </code></pre> |
| |
| <p>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.</p> |
| |
| <h1 id="building-thrift-with-gradle-without-cmakeautoconf">Building Thrift with Gradle without CMake/Autoconf</h1> |
| |
| <p>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.</p> |
| |
| <p>Currently we use gradle 8.0 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 <a href="https://docs.gradle.org/current/userguide/installation.html">gradle documentation</a>, or |
| following this step (which is also done in the travis CI docker images):</p> |
| |
| <p><code>bash |
| export GRADLE_VERSION="8.0.2" |
| # install dependencies |
| apt-get install -y --no-install-recommends openjdk-17-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 "ff7bf6a86f09b9b2c40bb8f48b25fc19cf2b2664fd1d220cd7ab833ec758d0d7 /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 |
| </code></p> |
| |
| <p>After the above step, <code>gradle</code> binary will be available in <code>/usr/local/bin/</code>. You can further choose |
| to locally create the gradle wrapper (even if they are ignored) using:</p> |
| |
| <p><code>bash |
| gradle wrapper --gradle-version $GRADLE_VERSION |
| </code></p> |
| |
| <p>To compile the Java Thrift libraries, simply do the following:</p> |
| |
| <p><code>bash |
| gradle |
| </code></p> |
| |
| <p>Yep, that’s easy. Look for <code>libthrift-<version>.jar</code> in the build/libs directory.</p> |
| |
| <p>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.</p> |
| |
| <ul> |
| <li>Build the Thrift executable from source at the default |
| location in the source tree. The project is configured |
| to look for it there.</li> |
| <li> |
| <p>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</p> |
| |
| <p>thrift.compiler=C:/Thrift/thrift.exe</p> |
| </li> |
| </ul> |
| |
| <p>To just build the library without running unit tests you simply do this.</p> |
| |
| <p><code>bash |
| gradle assemble |
| </code></p> |
| |
| <p>To install the library in the local Maven repository location |
| where other Maven or Gradle builds can reference it simply do this.</p> |
| |
| <p><code>bash |
| gradle publishToMavenLocal |
| </code></p> |
| |
| <p>The library will be placed in your home directory under .m2/repository</p> |
| |
| <p>To include Thrift in your applications simply add libthrift.jar to your |
| classpath, or install if in your default system classpath of choice.</p> |
| |
| <p>Build Thrift behind a proxy:</p> |
| |
| <p><code>bash |
| gradle -Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=8080 -Dhttp.proxyUser=thriftuser -Dhttp.proxyPassword=topsecret |
| </code></p> |
| |
| <p>or via</p> |
| |
| <p><code>bash |
| ./configure --with-java GRADLE_OPTS='-Dhttp.proxyHost=myproxyhost -Dhttp.proxyPort=8080 -Dhttp.proxyUser=thriftuser -Dhttp.proxyPassword=topsecret' |
| </code></p> |
| |
| <h1 id="unit-test-html-reports">Unit Test HTML Reports</h1> |
| |
| <p>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.</p> |
| |
| <h1 id="clover-code-coverage-for-thrift">Clover Code Coverage for Thrift</h1> |
| |
| <p>The build will optionally generate Clover Code coverage if the Gradle property |
| <code>cloverEnabled=true</code> is set in ~/.gradle/gradle.properties or on the command line |
| via <code>-PcloverEnabled=true</code>. 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.</p> |
| |
| <p>The following command will build, unit test, and generate Clover reports:</p> |
| |
| <p><code>bash |
| gradle -PcloverEnabled=true |
| </code></p> |
| |
| <h1 id="publishing-maven-artifacts-to-maven-central">Publishing Maven Artifacts to Maven Central</h1> |
| |
| <p>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:</p> |
| |
| <p><code>bash |
| make maven-publish -- This is for an Automake Linux build |
| make MavenPublish -- This is for a CMake generated build |
| </code></p> |
| |
| <p>The <code>publish</code> 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.</p> |
| |
| <p>```properties |
| # Signing key information for artifacts PGP signature (values are examples) |
| signing.keyId=24875D73 |
| signing.password=secret |
| signing.secretKeyRingFile=/Users/me/.gnupg/secring.gpg</p> |
| |
| <h1 id="apache-maven-staging-repository-user-credentials">Apache Maven staging repository user credentials</h1> |
| <p>mavenUser=meMyselfAndI |
| mavenPassword=MySuperAwesomeSecretPassword |
| ```</p> |
| |
| <p>NOTE: If you do not have a secring.gpg file, see the |
| <a href="https://docs.gradle.org/current/userguide/signing_plugin.html">gradle signing docs</a> |
| for instructions on how to generate it.</p> |
| |
| <p>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.</p> |
| |
| <p><code>bash |
| gradle -Prelease=true publish |
| </code></p> |
| |
| <p>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.</p> |
| |
| <p><code>properties |
| maven-repository-url=https://my.company.com/service/local/staging/deploy/maven2 |
| </code></p> |
| |
| <p>Or the same on the command line:</p> |
| |
| <p><code>bash |
| gradle -Pmaven-repository-url=https://my.company.com/service/local/staging/deploy/maven2 -Prelease=true -Pthrift.version=0.11.0 publish |
| </code></p> |
| |
| <h1 id="dependencies">Dependencies</h1> |
| |
| <p>Gradle |
| http://gradle.org/</p> |
| |
| <h1 id="breaking-changes">Breaking Changes</h1> |
| |
| <h2 id="section">0.13.0</h2> |
| |
| <ul> |
| <li> |
| <p>The signature of the ‘process’ method in TAsyncProcessor and TProcessor has |
| changed to remove the boolean return type and instead rely on Exceptions.</p> |
| </li> |
| <li> |
| <p>Per THRIFT-4805, TSaslTransportException has been removed. The same condition |
| is now covered by TTansportException, where <code>TTransportException.getType() == END_OF_FILE</code>.</p> |
| </li> |
| </ul> |
| |
| <h2 id="section-1">0.12.0</h2> |
| |
| <p>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.</p> |
| |
| <p>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.</p> |
| |
| <p class="snippet_footer">This page was generated by Apache Thrift's <strong>source tree docs</strong>: |
| <a href="https://gitbox.apache.org/repos/asf?p=thrift.git;a=blob;hb=HEAD;f=lib/java/README.md">lib/java/README.md</a> |
| </p> |
| |
| |
| </div> |
| <div class="container"> |
| <hr> |
| <footer class="footer"> |
| <div class="row"> |
| <div class="span3"> |
| <h3>Links</h3> |
| <ul class="unstyled"> |
| <li><a href="/download">Download</a></li> |
| <li><a href="/developers">Developers</a></li> |
| <li><a href="/tutorial">Tutorials</a></li> |
| </ul> |
| <ul class="unstyled"> |
| <li><a href="/sitemap">Sitemap</a></li> |
| </ul> |
| </div> |
| <div class="span3"> |
| <h3>Get Involved</h3> |
| <ul class="unstyled"> |
| <li><a href="/mailing">Mailing Lists</a></li> |
| <li><a href="http://issues.apache.org/jira/browse/THRIFT">Issue Tracking</a></li> |
| <li><a href="/docs/HowToContribute">How To Contribute</a></li> |
| </ul> |
| </div> |
| <div class="span6"> |
| <a href="http://www.apache.org/"><img src="/static/images/feather.svg" onerror="this.src='/static/images/feather.png';this.onerror=null;" /></a> |
| Copyright © 2023 <a href="http://www.apache.org/">Apache Software Foundation</a>. |
| Licensed under the <a href="http://www.apache.org/licenses/">Apache License v2.0</a>. |
| Apache, Apache Thrift, and the Apache feather logo are trademarks of The Apache Software Foundation. |
| </div> |
| </div> |
| </footer> |
| </div> |
| |
| </body> |
| </html> |