blob: 3f1fbdb1816a5776a246132f7b0d1aea7bbdaec0 [file] [log] [blame]
<!DOCTYPE html>
<html xmlns="" xml:lang="en" lang="en">
<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 - Thrift Type system</title>
<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="" target="_blank">Apache Home</a></li>
<li><a href="" target="_blank">Apache License v2.0</a></li>
<li><a href="" target="_blank">Donate</a></li>
<li><a href="" target="_blank">Thanks</a></li>
<li><a href="" target="_blank">Security</a></li>
<div class="container">
<h2 id="thrift-types">Thrift Types</h2>
<p>The Thrift type system is intended to allow programmers to use native types as much as possible, no matter what programming language they are working in. This information is based on, and supersedes, the information in the <a href="/static/files/thrift-20070401.pdf">Thrift Whitepaper</a>. The <a href="/docs/idl">Thrift IDL</a> provides descriptions of the types which are used to generate code for each target language.</p>
<h3 id="base-types">Base Types</h3>
<p>The base types were selected with the goal of simplicity and clarity rather than abundance, focusing on the key types available in all programming languages.</p>
<li>bool: A boolean value (true or false)</li>
<li>byte: An 8-bit signed integer</li>
<li>i16: A 16-bit signed integer</li>
<li>i32: A 32-bit signed integer</li>
<li>i64: A 64-bit signed integer</li>
<li>double: A 64-bit floating point number</li>
<li>string: A text string encoded using UTF-8 encoding</li>
<p>Note the absence of unsigned integer types. This is due to the fact that there are no native unsigned integer types in many programming languages.</p>
<h3 id="special-types">Special Types</h3>
<p>binary: a sequence of unencoded bytes</p>
<p>N.B.: This is currently a specialized form of the string type above, added to provide better interoperability with Java. The current plan-of-record is to elevate this to a base type at some point.</p>
<h3 id="structs">Structs</h3>
<p>Thrift structs define a common object – they are essentially equivalent to classes in OOP languages, but without inheritance. A struct has a set of strongly typed fields, each with a unique name identifier. Fields may have various annotations (numeric field IDs, optional default values, etc.) that are described in the <a href="/docs/idl">Thrift IDL</a>.</p>
<h3 id="containers">Containers</h3>
<p>Thrift containers are strongly typed containers that map to commonly used and commonly available container types in most programming languages.</p>
<p>There are three container types:</p>
<li>list<type>: An ordered list of elements. Translates to an STL vector, Java ArrayList, native arrays in scripting languages, etc.</type></li>
<li>set<type>: An unordered set of unique elements. Translates to an STL set, Java HashSet, set in Python, etc. Note: PHP does not support sets, so it is treated similar to a List</type></li>
<li>map&lt;type1,type2&gt;: A map of strictly unique keys to values. Translates to an STL map, Java HashMap, PHP associative array, Python/Ruby dictionary, etc.
While defaults are provided, the type mappings are not explicitly fixed. Custom code generator directives have been added to allow substitution of custom types in various destination languages.</li>
<p>Container elements may be of any valid Thrift Type.</p>
<p>N.B.: For maximal compatibility, the key type for map should be a basic type rather than a struct or container type. There are some languages which do not support more complex key types in their native map types. In addition the JSON protocol only supports key types that are base types.</p>
<h3 id="exceptions">Exceptions</h3>
<p>Exceptions are functionally equivalent to structs, except that they inherit from the native exception base class as appropriate in each target programming language, in order to seamlessly integrate with the native exception handling in any given language.</p>
<h3 id="services">Services</h3>
<p>Services are defined using Thrift types. Definition of a service is semantically equivalent to defining an interface (or a pure virtual abstract class) in object oriented programming. The Thrift compiler generates fully functional client and server stubs that implement the interface.</p>
<p>A service consists of a set of named functions, each with a list of parameters and a return type.</p>
<p>Note that void is a valid type for a function return, in addition to all other defined Thrift types. Additionally, an oneway modifier keyword may be added to a void function, which will generate code that does not wait for a response. Note that a pure void function will return a response to the client which guarantees that the operation has completed on the server side. With oneway method calls the client will only be guaranteed that the request succeeded at the transport layer. Oneway method calls of the same client may be executed in parallel/out of order by the server.</p>
<div class="container">
<footer class="footer">
<div class="row">
<div class="span3">
<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 class="unstyled">
<li><a href="/sitemap">Sitemap</a></li>
<div class="span3">
<h3>Get Involved</h3>
<ul class="unstyled">
<li><a href="/mailing">Mailing Lists</a></li>
<li><a href="">Issue Tracking</a></li>
<li><a href="/docs/HowToContribute">How To Contribute</a></li>
<div class="span6">
<a href=""><img src="/static/images/feather.svg" onerror="this.src='/static/images/feather.png';this.onerror=null;" /></a>
Copyright &copy; 2023 <a href="">Apache Software Foundation</a>.
Licensed under the <a href="">Apache License v2.0</a>.
Apache, Apache Thrift, and the Apache feather logo are trademarks of The Apache Software Foundation.