Author: jfarrell
Date: Wed May 16 01:47:13 2012
New Revision: 1338970
URL: http://svn.apache.org/viewvc?rev=1338970&view=rev
Log:
Thrift-1550: Adding concepts section from "the missing guide"
Added:
thrift/site/content/docs/concepts.md
thrift/site/publish/docs/concepts/
thrift/site/publish/docs/concepts/index.html
Modified:
thrift/site/publish/docs/index.html
thrift/site/publish/sitemap/index.html
Added: thrift/site/content/docs/concepts.md
URL:
http://svn.apache.org/viewvc/thrift/site/content/docs/concepts.md?rev=1338970&view=auto
==============================================================================
--- thrift/site/content/docs/concepts.md (added)
+++ thrift/site/content/docs/concepts.md Wed May 16 01:47:13 2012
@@ -0,0 +1,123 @@
+---
+title: "Concepts"
+kind: doc
+---
+## Thrift network stack
+Simple representation of the Apache Thrift networking stack
+<pre><code>
+ +-------------------------------------------+
+ | Server |
+ | (single-threaded, event-driven etc) |
+ +-------------------------------------------+
+ | Processor |
+ | (compiler generated) |
+ +-------------------------------------------+
+ | Protocol |
+ | (JSON, compact etc) |
+ +-------------------------------------------+
+ | Transport |
+ | (raw TCP, HTTP etc) |
+ +-------------------------------------------+
+</code></pre>
+
+## Transport
+The Transport layer provides a simple abstraction for reading/writing from/to
the network. This enables Thrift to decouple the underlying transport from the
rest of the system (serialization/deserialization, for instance).
+
+Here are some of the methods exposed by the **Transport** interface:
+
+* open
+* close
+* read
+* write
+* flush
+
+In addition to the **Transport** interface above, Thrift also uses a
**ServerTransport** interface used to accept or create primitive transport
objects. As the name suggest, **ServerTransport** is used mainly on the server
side to create new Transport objects for incoming connections.
+
+* open
+* listen
+* accept
+* close
+
+Here are some of the transports available for majority of the Thrift-supported
languages:
+
+* file: read/write to/from a file on disk
+* http: as the name suggests
+
+## Protocol
+
+The Protocol abstraction defines a mechanism to map in-memory data structures
to a wire-format. In other words, a protocol specifies how datatypes use the
+underlying Transport to encode/decode themselves. Thus the protocol
implementation governs the encoding scheme and is responsible for
(de)serialization. Some examples of protocols in this sense include JSON, XML,
plain text, compact binary etc.
+
+Here is the **Protocol** interface:
+
+<pre><code class="language-cpp">
+writeMessageBegin(name, type, seq)
+writeMessageEnd()
+writeStructBegin(name)
+writeStructEnd()
+writeFieldBegin(name, type, id)
+writeFieldEnd()
+writeFieldStop()
+writeMapBegin(ktype, vtype, size)
+writeMapEnd()
+writeListBegin(etype, size)
+writeListEnd()
+writeSetBegin(etype, size)
+writeSetEnd()
+writeBool(bool)
+writeByte(byte)
+writeI16(i16)
+writeI32(i32)
+writeI64(i64)
+writeDouble(double)
+writeString(string)
+
+name, type, seq = readMessageBegin()
+ readMessageEnd()
+name = readStructBegin()
+ readStructEnd()
+name, type, id = readFieldBegin()
+ readFieldEnd()
+k, v, size = readMapBegin()
+ readMapEnd()
+etype, size = readListBegin()
+ readListEnd()
+etype, size = readSetBegin()
+ readSetEnd()
+bool = readBool()
+byte = readByte()
+i16 = readI16()
+i32 = readI32()
+i64 = readI64()
+double = readDouble()
+string = readString()
+</code></pre>
+
+Thrift Protocols are stream oriented by design. There is no need for any
explicit framing. For instance, it is not necessary to know the length of a
+string or the number of items in a list before we start serializing them. Some
of the protocols available for majority of the Thrift-supported
+languages are:
+
+* binary: Fairly simple binary encoding -- the length and type of a field are
encoded as bytes followed by the actual value of the field.
+* compact: Described in
[THRIFT-110](https://issues.apache.org/jira/browse/THRIFT-110)
+* json
+
+## Processor
+A Processor encapsulates the ability to read data from input streams and write
to output streams. The input and output streams are represented by Protocol
+objects. The Processor interface is extremely simple
+
+<pre><code class="language-java">
+interface TProcessor {
+ bool process(TProtocol in, TProtocol out) throws TException
+}
+</code></pre>
+
+Service-specific processor implementations are generated by the compiler. The
Processor essentially reads data from the wire (using the input protocol),
+delegates processing to the handler (implemented by the user) and writes the
response over the wire (using the output protocol).
+
+## Server
+A Server pulls together all of the various features described above:
+
+* Create a transport
+* Create input/output protocols for the transport
+* Create a processor based on the input/output protocols
+* Wait for incoming connections and hand them off to the processor
Added: thrift/site/publish/docs/concepts/index.html
URL:
http://svn.apache.org/viewvc/thrift/site/publish/docs/concepts/index.html?rev=1338970&view=auto
==============================================================================
--- thrift/site/publish/docs/concepts/index.html (added)
+++ thrift/site/publish/docs/concepts/index.html Wed May 16 01:47:13 2012
@@ -0,0 +1,223 @@
+<!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/bootstrap.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>
+
+ <title>Apache Thrift</title>
+ </head>
+ <body>
+ <div class="navbar">
+ <div class="navbar-inner">
+ <div class="container">
+ <a class="brand" href="http://thrift.apache.org";>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="/tutorial/">Tutorials</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://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">
+ <h2>Thrift network stack</h2>
+
+<p>Simple representation of the Apache Thrift networking stack
+</p><pre><code>
+ +-------------------------------------------+
+ | Server |
+ | (single-threaded, event-driven etc) |
+ +-------------------------------------------+
+ | Processor |
+ | (compiler generated) |
+ +-------------------------------------------+
+ | Protocol |
+ | (JSON, compact etc) |
+ +-------------------------------------------+
+ | Transport |
+ | (raw TCP, HTTP etc) |
+ +-------------------------------------------+
+</code></pre>
+
+<h2>Transport</h2>
+
+<p>The Transport layer provides a simple abstraction for reading/writing
from/to the network. This enables Thrift to decouple the underlying transport
from the rest of the system (serialization/deserialization, for instance).</p>
+
+<p>Here are some of the methods exposed by the <strong>Transport</strong>
interface:</p>
+
+<ul>
+<li>open</li>
+<li>close</li>
+<li>read</li>
+<li>write</li>
+<li>flush</li>
+</ul><p>In addition to the <strong>Transport</strong> interface above, Thrift
also uses a <strong>ServerTransport</strong> interface used to accept or create
primitive transport objects. As the name suggest,
<strong>ServerTransport</strong> is used mainly on the server side to create
new Transport objects for incoming connections.</p>
+
+<ul>
+<li>open</li>
+<li>listen</li>
+<li>accept</li>
+<li>close</li>
+</ul><p>Here are some of the transports available for majority of the
Thrift-supported languages:</p>
+
+<ul>
+<li>file: read/write to/from a file on disk</li>
+<li>http: as the name suggests</li>
+</ul><h2>Protocol</h2>
+
+<p>The Protocol abstraction defines a mechanism to map in-memory data
structures to a wire-format. In other words, a protocol specifies how datatypes
use the
+underlying Transport to encode/decode themselves. Thus the protocol
implementation governs the encoding scheme and is responsible for
(de)serialization. Some examples of protocols in this sense include JSON, XML,
plain text, compact binary etc.</p>
+
+<p>Here is the <strong>Protocol</strong> interface:</p>
+
+<pre><code class="language-cpp">writeMessageBegin(name, type, seq)
+writeMessageEnd()
+writeStructBegin(name)
+writeStructEnd()
+writeFieldBegin(name, type, id)
+writeFieldEnd()
+writeFieldStop()
+writeMapBegin(ktype, vtype, size)
+writeMapEnd()
+writeListBegin(etype, size)
+writeListEnd()
+writeSetBegin(etype, size)
+writeSetEnd()
+writeBool(<span style="color:#0a5;font-weight:bold">bool</span>)
+writeByte(byte)
+writeI16(i16)
+writeI32(i32)
+writeI64(i64)
+writeDouble(<span style="color:#0a5;font-weight:bold">double</span>)
+writeString(<span style="color:#0a5;font-weight:bold">string</span>)
+
+name, type, seq = readMessageBegin()
+ readMessageEnd()
+name = readStructBegin()
+ readStructEnd()
+name, type, id = readFieldBegin()
+ readFieldEnd()
+k, v, size = readMapBegin()
+ readMapEnd()
+etype, size = readListBegin()
+ readListEnd()
+etype, size = readSetBegin()
+ readSetEnd()
+<span style="color:#0a5;font-weight:bold">bool</span> = readBool()
+byte = readByte()
+i16 = readI16()
+i32 = readI32()
+i64 = readI64()
+<span style="color:#0a5;font-weight:bold">double</span> = readDouble()
+<span style="color:#0a5;font-weight:bold">string</span> =
readString()</code></pre>
+
+<p>Thrift Protocols are stream oriented by design. There is no need for any
explicit framing. For instance, it is not necessary to know the length of a
+string or the number of items in a list before we start serializing them. Some
of the protocols available for majority of the Thrift-supported
+languages are:</p>
+
+<ul>
+<li>binary: Fairly simple binary encoding â the length and type of a field
are encoded as bytes followed by the actual value of the field.</li>
+<li>compact: Described in <a
href="https://issues.apache.org/jira/browse/THRIFT-110";>THRIFT-110</a>
+</li>
+<li>json</li>
+</ul><h2>Processor</h2>
+
+<p>A Processor encapsulates the ability to read data from input streams and
write to output streams. The input and output streams are represented by
Protocol
+objects. The Processor interface is extremely simple</p>
+
+<pre><code class="language-java"><span
style="color:#339;font-weight:bold">interface</span> <span
style="color:#B06;font-weight:bold">TProcessor</span> {
+ bool process(TProtocol in, TProtocol out) <span
style="color:#088;font-weight:bold">throws</span> TException
+}</code></pre>
+
+<p>Service-specific processor implementations are generated by the compiler.
The Processor essentially reads data from the wire (using the input protocol),
+delegates processing to the handler (implemented by the user) and writes the
response over the wire (using the output protocol).</p>
+
+<h2>Server</h2>
+
+<p>A Server pulls together all of the various features described above:</p>
+
+<ul>
+<li>Create a transport</li>
+<li>Create input/output protocols for the transport</li>
+<li>Create a processor based on the input/output protocols</li>
+<li>Wait for incoming connections and hand them off to the processor</li>
+</ul>
+ </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/favicon.ico" /></a> Copyright 2012 <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>
Modified: thrift/site/publish/docs/index.html
URL:
http://svn.apache.org/viewvc/thrift/site/publish/docs/index.html?rev=1338970&r1=1338969&r2=1338970&view=diff
==============================================================================
--- thrift/site/publish/docs/index.html (original)
+++ thrift/site/publish/docs/index.html Wed May 16 01:47:13 2012
@@ -72,6 +72,10 @@
</li>
<li>
+ <a href="/docs/concepts/">Concepts</a>
+ </li>
+
+ <li>
<a href="/docs/features/">Features</a>
</li>
Modified: thrift/site/publish/sitemap/index.html
URL:
http://svn.apache.org/viewvc/thrift/site/publish/sitemap/index.html?rev=1338970&r1=1338969&r2=1338970&view=diff
==============================================================================
--- thrift/site/publish/sitemap/index.html (original)
+++ thrift/site/publish/sitemap/index.html Wed May 16 01:47:13 2012
@@ -77,7 +77,7 @@
<li>
<a href="/docs/">Documentation</a><ul>
-<li><a href="/docs/BuildingFromSource/">Building From Source</a></li> <li><a
href="/docs/features/">Features</a></li> <li><a
href="/docs/HowToContribute/">How To Contribute</a></li> <li>
+<li><a href="/docs/BuildingFromSource/">Building From Source</a></li> <li><a
href="/docs/concepts/">Concepts</a></li> <li><a
href="/docs/features/">Features</a></li> <li><a
href="/docs/HowToContribute/">How To Contribute</a></li> <li>
<a href="/docs/committers/">Information for Committers</a> <ul>
<li><a href="/docs/committers/AdditionalReading/">General articles and links
for committers</a></li> <li><a href="/docs/committers/HowToRelease/">How
to create a release</a></li> <li><a
href="/docs/committers/HowToPublish/">How to publish a release</a></li>
<li><a href="/docs/committers/HowToThriftWebsite/">How to update the
website</a></li> <li><a href="/docs/committers/HowToVersion/">How to
version client libraries</a></li> </ul>
</li> <li>
