[
https://issues.apache.org/jira/browse/THRIFT-3867?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15358089#comment-15358089
]
ASF GitHub Bot commented on THRIFT-3867:
----------------------------------------
Github user Jens-G commented on a diff in the pull request:
https://github.com/apache/thrift/pull/1036#discussion_r69231154
--- Diff: doc/specs/thrift-binary-protocol-encoding.md ---
@@ -0,0 +1,467 @@
+Thrift Protocol Encoding for BinaryProtocol and CompactProtocol
+====================================================================
+
+Last Modified: 2016-Jun-29
+
+! WARNING !
+
+This document is _work in progress_ and should not (yet) be seen as an
authoritative source of information.
+
+This text is submitted to the Thrift community for review and improvements.
+
+--------------------------------------------------------------------
+
+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.
+
+--------------------------------------------------------------------
+
+There are many ways to encode Thrift on the wire. This documents focuses
on the wire encoding for services calls
+(encoding and semantics) in the Thrift older *binary protocol* (which has
not been documented before) and the
+*compact protocol*. Both the regular socket transport (unframed) and the
framed transport are described.
+
+Note that no effort is made to group descriptions of behavior of the
Thrift server and the encodings used in the
+Thrift wire format. The order in which things are described is such that
you can read the document from top to bottom.
+
+The information here is mostly based on the Java implementation in the
Apache thrift library (version 0.9.1) and
+[THRIFT-110 A more compact
format](https://issues.apache.org/jira/browse/THRIFT-110). Other implementation
however,
+should behave the same.
+
+## Message exchange
+
+Both the binary protocol and the compact protocol assume a transport layer
that exposes a bi-directional byte stream,
+for example a TCP socket. Both use the following message exchange:
+
+1. Client sends a `TMessage` (type `Call`). The TMessage contains some
metadata and the name of the method to invoke.
+2. Client sends method arguments (a struct defined by the generate code).
+3. Server sends a `TMessage` (type `Response` or `Exception`) to start the
response.
+4. Server sends completes response with a struct (a predefined struct or
one defined by generated code).
+
+The pattern is a simple half duplex protocol where the parties alternate
in sending a `TMessage` followed by a struct.
+What these are is described below.
+
+Although the standard Apache Thrift Java clients do not support pipelining
(sending multiple requests without waiting
+for an response), the standard Apache Thrift Java servers do support it.
+
+## TMessage
+
+A *TMessage* contains the following information:
+
+* _Message type_, a message types, one of `Call`, `Reply`, `Exception` and
`Oneway`.
+* _Sequence id_, an int32 integer.
+* _Name_, a string (can be empty).
+
+The *sequence id* is a simple message id assigned by the client. The
server will use the same sequence id in the
+TMessage of the response. The client uses this number to detect out of
order responses. Each client has a int32 field
+which is increased for each message. The sequence id simply wraps around
when it overflows.
+
+The *name* indicates the service method name to invoke. The server uses
the same name in the TMessage of the response.
+
+When the *multiplexed protocol* is used, the name contains the service
name, a colon `:` and the method name. The
+multiplexed protocol is not compatible with other protocols.
+
+The *message type* indicates what kind of message is sent.
+
+Clients send requests with TMessages of type `Call` or `Oneway` (step 1 in
the protocol exchange). Servers send
+responses with TMessages of type `Exception` or `Reply`.
+
+### Oneway
+
+Type `Oneway` is only used starting from Apache Thrift 0.9.3. Earlier
versions do _not_ send TMessages of type `Oneway`,
+even for service methods defined with the `oneway` modifier.
+
+When client sends a request with type `Oneway`, the server must _not_ send
a response (steps 3 and 4 are skipped).
+Strangely enough (in the Java code generated by Apache Thrift 0.9.1 up to
0.9.3), only responses of type `Response` are
+skipped. Responses of type `Exception` are always send. There is no
correct way to handle this situation from the client
+perspective; you either wait for a response or not, you can't do both.
Luckily this has been fixed _after_ Apache Thrift
--- End diff --
The Thrift compiler prevents the combination of ```oneway``` plus
```throws``` right from the start [since March
2003](https://github.com/apache/thrift/commit/6d94390375e865e0c774df1dc072ea1774eba7b1),
any types other than ```void``` are disallowed since
[THRIFT-2030](https://issues.apache.org/jira/browse/THRIFT-2030). So that does
not hold.
> Specify BinaryProtocol and CompactProtocol
> ------------------------------------------
>
> Key: THRIFT-3867
> URL: https://issues.apache.org/jira/browse/THRIFT-3867
> Project: Thrift
> Issue Type: Documentation
> Components: Documentation
> Reporter: Erik van Oosten
>
> It would be nice when the protocol(s) would be specified somewhere. This
> should improve communication between developers, but also opens the way for
> alternative implementations so that Thrift can thrive even better.
> I have a fairly complete description of the BinaryProtocol and
> CompactProtocol which I will submit as a patch for further review and
> discussion.
--
This message was sent by Atlassian JIRA
(v6.3.4#6332)
