blob: d22c143cf443528738bbdddaff878c70813e1596 [file] [log] [blame]
<!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 - Home</title>
</head>
<body>
<div class="navbar">
<div class="navbar-inner">
<div class="container">
<a class="brand" href="/">Apache Thrift &trade;</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">
<div class="row">
<div class="span8">
<p>
The Apache Thrift software framework, for scalable cross-language services development, combines a software stack with a code generation engine to build services that work efficiently and seamlessly between C++, Java, Python, PHP, Ruby, Erlang, Perl, Haskell, C#, Cocoa, JavaScript, Node.js, Smalltalk, OCaml and Delphi and other languages.
</p>
<h3>Getting Started</h3>
<p>
<ul>
<li>
<b>Download Apache Thrift</b>
<p>To get started, <a href="/download">download</a> a copy of Thrift.</p>
</li>
<li>
<b>Build and Install the Apache Thrift compiler</b>
<p>You will then need to <a href="/docs/BuildingFromSource">build</a> the Apache Thrift compiler and install it. See the <a href="/docs/install">installing Thrift</a> guide for any help with this step.</p>
</li>
<li>
<b>Writing a .thrift file</b>
<p>After the Thrift compiler is installed you will need to create a thrift file. This file is an <a href="/docs/idl">interface definition</a> made up of <a href="/docs/types">thrift types</a> and Services. The services you define in this file are implemented by the server and are called by any clients. The Thrift compiler is used to generate your Thrift File into source code which is used by the different client libraries and the server you write. To generate the source from a thrift file run</p>
<pre><code>thrift --gen &lt;language&gt; &lt;Thrift filename&gt;</code></pre>
<p>The sample tutorial.thrift file used for all the client and server tutorials can be found <a href="https://github.com/apache/thrift/tree/master/tutorial">here</a>. </p>
</li>
</ul>
</p>
<br />
<p>
To learn more about Apache Thrift <a href="/static/files/thrift-20070401.pdf">Read the Whitepaper</a>
</p>
</div>
<div class="span3 well center pull-right">
<h2>Download</h2>
<p>Apache Thrift v0.18.1</p>
<p>
<a class="btn btn-large" href="http://www.apache.org/dyn/closer.cgi?path=/thrift/0.18.1/thrift-0.18.1.tar.gz">
Download <small>v0.18.1</small>
</a>
</p>
<p>
<small>
<a href="https://www.apache.org/dist/thrift/0.18.1/thrift-0.18.1.tar.gz.md5">MD5</a>
</small>
|
<small>
<a href="https://www.apache.org/dist/thrift/0.18.1/thrift-0.18.1.tar.gz.asc">PGP</a>
</small>
</p>
<p>
<h4>[<a href="/download">Other Downloads</a>]</h4>
</p>
</div>
</div>
<hr />
<h3>Example</h3>
<p>Apache Thrift allows you to define data types and service interfaces in a simple definition file. Taking that file as input, the compiler generates code to be used to easily build RPC clients and servers that communicate seamlessly across programming languages. Instead of writing a load of boilerplate code to serialize and transport your objects and invoke remote methods, you can get right down to business.</p>
<p>The following example is a simple service to store user objects for a web front end.</p>
<div class="tabbable">
<ul class="nav nav-tabs">
<li class="active"><a href="#1" data-toggle="tab">Thrift Definition File</a></li>
<li><a href="#2" data-toggle="tab">Python Client</a></li>
<li><a href="#3" data-toggle="tab">Java Server</a></li>
</ul>
<div class="tab-content">
<div class="tab-pane active" id="1">
<div class="highlight"><pre class="codehilite"><code>/**
* Ahh, now onto the cool part, defining a service. Services just need a name
* and can optionally inherit from another service using the extends keyword.
*/
service Calculator extends shared.SharedService {
/**
* A method definition looks like C code. It has a return type, arguments,
* and optionally a list of exceptions that it may throw. Note that argument
* lists and exception lists are specified using the exact same syntax as
* field lists in struct or exception definitions.
*/
void ping(),
i32 add(1:i32 num1, 2:i32 num2),
i32 calculate(1:i32 logid, 2:Work w) throws (1:InvalidOperation ouch),
/**
* This method has a oneway modifier. That means the client only makes
* a request and does not listen for any response at all. Oneway methods
* must be void.
*/
oneway void zip()
}
</code></pre></div>
<p class="snippet_footer">This snippet 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=tutorial/tutorial.thrift">tutorial/tutorial.thrift</a>
</p>
</div>
<div class="tab-pane" id="2">
<div class="highlight"><pre class="codehilite"><code><span class="k">def</span> <span class="nf">main</span><span class="p">():</span>
<span class="c1"># Make socket
</span> <span class="n">transport</span> <span class="o">=</span> <span class="n">TSocket</span><span class="p">.</span><span class="n">TSocket</span><span class="p">(</span><span class="s">'localhost'</span><span class="p">,</span> <span class="mi">9090</span><span class="p">)</span>
<span class="c1"># Buffering is critical. Raw sockets are very slow
</span> <span class="n">transport</span> <span class="o">=</span> <span class="n">TTransport</span><span class="p">.</span><span class="n">TBufferedTransport</span><span class="p">(</span><span class="n">transport</span><span class="p">)</span>
<span class="c1"># Wrap in a protocol
</span> <span class="n">protocol</span> <span class="o">=</span> <span class="n">TBinaryProtocol</span><span class="p">.</span><span class="n">TBinaryProtocol</span><span class="p">(</span><span class="n">transport</span><span class="p">)</span>
<span class="c1"># Create a client to use the protocol encoder
</span> <span class="n">client</span> <span class="o">=</span> <span class="n">Calculator</span><span class="p">.</span><span class="n">Client</span><span class="p">(</span><span class="n">protocol</span><span class="p">)</span>
<span class="c1"># Connect!
</span> <span class="n">transport</span><span class="p">.</span><span class="nb">open</span><span class="p">()</span>
<span class="n">client</span><span class="p">.</span><span class="n">ping</span><span class="p">()</span>
<span class="k">print</span><span class="p">(</span><span class="s">'ping()'</span><span class="p">)</span>
<span class="n">sum_</span> <span class="o">=</span> <span class="n">client</span><span class="p">.</span><span class="n">add</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">1</span><span class="p">)</span>
</code></pre></div>
<p class="snippet_footer">This snippet 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=tutorial/py/PythonClient.py">tutorial/py/PythonClient.py</a>
</p>
</div>
<div class="tab-pane" id="3">
Initialize the Server:
<div class="highlight"><pre class="codehilite"><code> <span class="k">try</span> <span class="o">{</span>
<span class="nc">TServerTransport</span> <span class="n">serverTransport</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">TServerSocket</span><span class="o">(</span><span class="mi">9090</span><span class="o">);</span>
<span class="nc">TServer</span> <span class="n">server</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">TSimpleServer</span><span class="o">(</span><span class="k">new</span> <span class="nc">Args</span><span class="o">(</span><span class="n">serverTransport</span><span class="o">).</span><span class="na">processor</span><span class="o">(</span><span class="n">processor</span><span class="o">));</span>
<span class="c1">// Use this for a multithreaded server</span>
<span class="c1">// TServer server = new TThreadPoolServer(new TThreadPoolServer.Args(serverTransport).processor(processor));</span>
<span class="nc">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"Starting the simple server..."</span><span class="o">);</span>
<span class="n">server</span><span class="o">.</span><span class="na">serve</span><span class="o">();</span>
<span class="o">}</span> <span class="k">catch</span> <span class="o">(</span><span class="nc">Exception</span> <span class="n">e</span><span class="o">)</span> <span class="o">{</span>
<span class="n">e</span><span class="o">.</span><span class="na">printStackTrace</span><span class="o">();</span>
<span class="o">}</span>
</code></pre></div>
<p class="snippet_footer">This snippet 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=tutorial/java/src/JavaServer.java">tutorial/java/src/JavaServer.java</a>
</p>
The CalculatorHandler:
<div class="highlight"><pre class="codehilite"><code><span class="kd">public</span> <span class="kd">class</span> <span class="nc">CalculatorHandler</span> <span class="kd">implements</span> <span class="nc">Calculator</span><span class="o">.</span><span class="na">Iface</span> <span class="o">{</span>
<span class="kd">private</span> <span class="nc">HashMap</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">,</span><span class="nc">SharedStruct</span><span class="o">&gt;</span> <span class="n">log</span><span class="o">;</span>
<span class="kd">public</span> <span class="nf">CalculatorHandler</span><span class="o">()</span> <span class="o">{</span>
<span class="n">log</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">HashMap</span><span class="o">&lt;</span><span class="nc">Integer</span><span class="o">,</span> <span class="nc">SharedStruct</span><span class="o">&gt;();</span>
<span class="o">}</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">ping</span><span class="o">()</span> <span class="o">{</span>
<span class="nc">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"ping()"</span><span class="o">);</span>
<span class="o">}</span>
<span class="kd">public</span> <span class="kt">int</span> <span class="nf">add</span><span class="o">(</span><span class="kt">int</span> <span class="n">n1</span><span class="o">,</span> <span class="kt">int</span> <span class="n">n2</span><span class="o">)</span> <span class="o">{</span>
<span class="nc">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"add("</span> <span class="o">+</span> <span class="n">n1</span> <span class="o">+</span> <span class="s">","</span> <span class="o">+</span> <span class="n">n2</span> <span class="o">+</span> <span class="s">")"</span><span class="o">);</span>
<span class="k">return</span> <span class="n">n1</span> <span class="o">+</span> <span class="n">n2</span><span class="o">;</span>
<span class="o">}</span>
<span class="kd">public</span> <span class="kt">int</span> <span class="nf">calculate</span><span class="o">(</span><span class="kt">int</span> <span class="n">logid</span><span class="o">,</span> <span class="nc">Work</span> <span class="n">work</span><span class="o">)</span> <span class="kd">throws</span> <span class="nc">InvalidOperation</span> <span class="o">{</span>
<span class="nc">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"calculate("</span> <span class="o">+</span> <span class="n">logid</span> <span class="o">+</span> <span class="s">", {"</span> <span class="o">+</span> <span class="n">work</span><span class="o">.</span><span class="na">op</span> <span class="o">+</span> <span class="s">","</span> <span class="o">+</span> <span class="n">work</span><span class="o">.</span><span class="na">num1</span> <span class="o">+</span> <span class="s">","</span> <span class="o">+</span> <span class="n">work</span><span class="o">.</span><span class="na">num2</span> <span class="o">+</span> <span class="s">"})"</span><span class="o">);</span>
<span class="kt">int</span> <span class="n">val</span> <span class="o">=</span> <span class="mi">0</span><span class="o">;</span>
<span class="k">switch</span> <span class="o">(</span><span class="n">work</span><span class="o">.</span><span class="na">op</span><span class="o">)</span> <span class="o">{</span>
<span class="k">case</span> <span class="nl">ADD:</span>
<span class="n">val</span> <span class="o">=</span> <span class="n">work</span><span class="o">.</span><span class="na">num1</span> <span class="o">+</span> <span class="n">work</span><span class="o">.</span><span class="na">num2</span><span class="o">;</span>
<span class="k">break</span><span class="o">;</span>
<span class="k">case</span> <span class="nl">SUBTRACT:</span>
<span class="n">val</span> <span class="o">=</span> <span class="n">work</span><span class="o">.</span><span class="na">num1</span> <span class="o">-</span> <span class="n">work</span><span class="o">.</span><span class="na">num2</span><span class="o">;</span>
<span class="k">break</span><span class="o">;</span>
<span class="k">case</span> <span class="nl">MULTIPLY:</span>
<span class="n">val</span> <span class="o">=</span> <span class="n">work</span><span class="o">.</span><span class="na">num1</span> <span class="o">*</span> <span class="n">work</span><span class="o">.</span><span class="na">num2</span><span class="o">;</span>
<span class="k">break</span><span class="o">;</span>
<span class="k">case</span> <span class="nl">DIVIDE:</span>
<span class="k">if</span> <span class="o">(</span><span class="n">work</span><span class="o">.</span><span class="na">num2</span> <span class="o">==</span> <span class="mi">0</span><span class="o">)</span> <span class="o">{</span>
<span class="nc">InvalidOperation</span> <span class="n">io</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">InvalidOperation</span><span class="o">();</span>
<span class="n">io</span><span class="o">.</span><span class="na">whatOp</span> <span class="o">=</span> <span class="n">work</span><span class="o">.</span><span class="na">op</span><span class="o">.</span><span class="na">getValue</span><span class="o">();</span>
<span class="n">io</span><span class="o">.</span><span class="na">why</span> <span class="o">=</span> <span class="s">"Cannot divide by 0"</span><span class="o">;</span>
<span class="k">throw</span> <span class="n">io</span><span class="o">;</span>
<span class="o">}</span>
<span class="n">val</span> <span class="o">=</span> <span class="n">work</span><span class="o">.</span><span class="na">num1</span> <span class="o">/</span> <span class="n">work</span><span class="o">.</span><span class="na">num2</span><span class="o">;</span>
<span class="k">break</span><span class="o">;</span>
<span class="k">default</span><span class="o">:</span>
<span class="nc">InvalidOperation</span> <span class="n">io</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">InvalidOperation</span><span class="o">();</span>
<span class="n">io</span><span class="o">.</span><span class="na">whatOp</span> <span class="o">=</span> <span class="n">work</span><span class="o">.</span><span class="na">op</span><span class="o">.</span><span class="na">getValue</span><span class="o">();</span>
<span class="n">io</span><span class="o">.</span><span class="na">why</span> <span class="o">=</span> <span class="s">"Unknown operation"</span><span class="o">;</span>
<span class="k">throw</span> <span class="n">io</span><span class="o">;</span>
<span class="o">}</span>
<span class="nc">SharedStruct</span> <span class="n">entry</span> <span class="o">=</span> <span class="k">new</span> <span class="nc">SharedStruct</span><span class="o">();</span>
<span class="n">entry</span><span class="o">.</span><span class="na">key</span> <span class="o">=</span> <span class="n">logid</span><span class="o">;</span>
<span class="n">entry</span><span class="o">.</span><span class="na">value</span> <span class="o">=</span> <span class="nc">Integer</span><span class="o">.</span><span class="na">toString</span><span class="o">(</span><span class="n">val</span><span class="o">);</span>
<span class="n">log</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="n">logid</span><span class="o">,</span> <span class="n">entry</span><span class="o">);</span>
<span class="k">return</span> <span class="n">val</span><span class="o">;</span>
<span class="o">}</span>
<span class="kd">public</span> <span class="nc">SharedStruct</span> <span class="nf">getStruct</span><span class="o">(</span><span class="kt">int</span> <span class="n">key</span><span class="o">)</span> <span class="o">{</span>
<span class="nc">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"getStruct("</span> <span class="o">+</span> <span class="n">key</span> <span class="o">+</span> <span class="s">")"</span><span class="o">);</span>
<span class="k">return</span> <span class="n">log</span><span class="o">.</span><span class="na">get</span><span class="o">(</span><span class="n">key</span><span class="o">);</span>
<span class="o">}</span>
<span class="kd">public</span> <span class="kt">void</span> <span class="nf">zip</span><span class="o">()</span> <span class="o">{</span>
<span class="nc">System</span><span class="o">.</span><span class="na">out</span><span class="o">.</span><span class="na">println</span><span class="o">(</span><span class="s">"zip()"</span><span class="o">);</span>
<span class="o">}</span>
<span class="o">}</span>
</code></pre></div>
<p class="snippet_footer">This snippet 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=tutorial/java/src/CalculatorHandler.java">tutorial/java/src/CalculatorHandler.java</a>
</p>
</div>
</div>
</div>
</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 &copy; 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>