You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@thrift.apache.org by Johan Stuyts <j....@zybber.nl> on 2008/09/09 14:40:41 UTC

Redesign of the Java API

Hi,

I thought the move from Facebook to Apache packages might be an  
opportunity to redesign the Java API. Redesigning the API at this stage  
means that there are no backward compatibility issues: you either use the  
old or the new packages. A switch can be added to the compiler to choose  
between code that uses the old or the new packages.

Why can a redesign be beneficial?
- A different set of functions for TProtocol so protocol implementations  
have more flexibility (For example see  
https://issues.apache.org/jira/browse/THRIFT-110 (Changes to the IDL would  
still be required to be able to implement a compact format)).
- Support for changes to the IDL needed to support more formats (e.g. the  
compact format) if the IDL is changed.
- Properly supporting optional members of structures.
- Removal of the name when writing the beginning of the structure as  
nobody seems to need this  
(https://issues.apache.org/jira/browse/THRIFT-8). There is no need to hang  
on to obsolete constructs and confuse new users.
- Replace base classes with interfaces so implementations that want to do  
things differently do not have to extend the base class awkwardly. For  
example: TProtocol and TServer.
- Refactoring of strange constructs in the current API. For example: the  
'getTransport(TTransport)' method of TTransportFactory is used as a  
transport transformer in addition to being used as a factory. When used as  
a factory method the parameter makes no sense.
- Remove the Client and Processor classes from generated code of services  
so server and client implementations have more freedom concerning how  
(service and) function selection information is communicated and  
processed, and how I/O is handled. See below.
- Drop transports. See below.
- Add an interface to the generated code and add support classes for doing  
asynchronous calls (i.e. support for sequence IDs). See below.
- Drop the many constructors of a number of classes and replace them with  
a single constructor taking an options object.
- Drop the 'T' prefix of types as this is not customary in Java.

Removal of Client and Processor
===============================
It is impossible for the client and server implementations to handle  
services in a generic way currently. The only types available are  
TProcessorFactory and TProcessor. These types do not provide enough  
information. For example: for some server implementations it is  
interesting to know whether or not a function has the 'async' keyword. If  
a function does have it, the communication channel can be released  
immediatly instead of being held onto while the asynchronous function is  
running.

In addition, the assumption that the protocol can be assigned to the  
classes Client and Processor once, makes it more difficult to implement  
multiplexing servers (which also need to send the service name in addition  
to the function name), clients and servers using non-blocking I/O,  
connection pooling clients, asynchronous calls, etc. It would be much  
better if client and server implementations have more control over how  
they want to handle things before passing control to the function  
implementations.

By only supplying the minimal information about services and functions to  
client and server implementations, and by passing the protocol as late as  
possible to function implementations, lots of flexibility is gained. Here  
is a rough draft of how the API would look like (from the perspective of  
the server. Information and methods needed for client implementations are  
missing):
class Service {
   Function get(String);
}
class Function {
   boolean isAsynchronous();

   // Throws an exception if function is asynchronous.
   //
   // Only reads the structure containing the parameters
   // using the protocol. Messages are handled by the
   // server.
   //
   // Returns the wrapper around the result.
   //
   // Server can decide when to write the result without
   // having to copy it to a byte array.
   Base invoke(Protocol);

   // Discards result if function is synchronous.
   //
   // Only reads the structure containing the parameters
   // using the protocol. Messages are handled by the
   // server.
   void invoke(Protocol);
}

Another example that could be built is a client that requests the mapping  
of (services and) functions to IDs from the server, so invocation of a  
particular function does not require the sending of the (service and)  
function names. Instead a few bytes are all that is needed to select a  
function. This is very difficult to do now because the Client and  
Processor classes have control over the information of the message being  
sent.

For the multiplexing server that I want to build having more freedom could  
mean replacing this request header:
i32:    version and type
string: service name
i32:    sequence ID (unused)
i32:    version and type
string: function name
i32:    sequence ID

With this request header (if I implement the function to ID mapping). This  
saves (for a 15-character ASCII service name, a 10-character ASCII  
function name and less than 16384 functions) 42-43 bytes per function  
invocation:
byte:   version and type
vint:   function ID (1 or 2 bytes)
i32:    sequence ID

If I would use one bit of the version and type byte as a flag to indicate  
sequence IDs are not needed, another 4 bytes could be saved, i.e. only 2-3  
bytes would be needed to select a function.

Note that protocols must understand more header types than 'TMessage' for  
this to work. Maybe the clients and servers must be given the freedom to  
write the header instead of having a single message type. Not all clients  
and servers can have their own header format because that would defeat  
interoperability, instead a number of header formats have to be agreed  
upon. For example:
- Current header format for single-service clients and servers.
- New header format for multiplexed clients and servers with support for:
   - a function to ID map for more efficient function selection;
   - indicating a sequence ID is not needed.

Removal of the Client and Processor classes will also remove a lot of  
duplicate code for handling calls from the generated classes. In my  
opinion this duplicate code can easily be transformed into generic code in  
client and server implementations.

Drop transports
===============
All servers currently require a transport, but the internal workings of a  
server are closely tied to a specific transport. Why have servers work  
with wrappers around sockets instead of working with sockets directly?  
Possibilities for server implementation will now be limited by the  
wrappers instead of allowing the full flexibility of the socket API.

In my opinion a transport is internal to a server. If a server can be  
implemented in a better way, the thin transport wrapper around sockets  
should not be a limiting factor. It would be very cumbersome if an API  
change of a 'TServerTransport' implementation is needed to be able to  
implement a server differently.

The only thing that needs to be handled is 'TFramedTransport' because this  
is a decorator. In my opinion it may be better to implement it as a  
protocol decorator which frames messages.

I don't know how this works out for clients but I think it would be very  
similar.

Asynchronous interface
======================
(Does anyone have a better name than 'asynchronous functions' so the  
'async' keyword and sequence IDs cannot be confused?)

The addition of an asynchronous interface (to support sequence IDs)  
besides the synchronous one makes it easier to implement asynchronous  
calls (using sequence IDs). Asynchronous calls need to be handled  
differently by a client anyway, so it is best to make this distinction  
clear. For some languages only asynchronous interfaces might be generated.  
Here is a rough draft of how this would look if polling is used to  
retrieve the response:
interface Calculator.IfaceAsync {
   AsynchronousCall ping();
   IntAsynchronousCall add(int, int);
   IntAsynchronousCall calculate(int, Work);
   // zip() not added because it does not return a result
}
interface AsynchronousCall {
   boolean hasResponseArrived();
}
interface IntAsynchronousCall extends AsynchronousCall {
   int getResult();
}
interface StructAsynchronousCall<R> extends AsynchronousCall {
   R getResult();
}

An alternative is to use events instead of polling:
interface Calculator.IfaceAsync {
   void ping(VoidAsynchronousCompletion);
   void add(int, int, IntAsynchronousCompletion);
   void calculate(int, Work, IntAsynchronousCompletion);
   // zip() not added because it does not return a result
}
interface VoidAsynchronousCompletion {
   void handleResponse();
}
interface IntAsynchronousCompletion {
   void handleResponse(int);
}
interface StructAsynchronousCompletion<R> {
   void handleResponse(R);
}


What do you think? Would a redesign be useful and worth it?

-- 
Kind regards,

Johan Stuyts

Re: Redesign of the Java API

Posted by Johan Stuyts <j....@zybber.nl>.
> One other thing that I forgot to mention is that I would be in favor
> of adding a new message type for asynchronous calls, even though
> it would changing the wire format and could be kind of a pain to roll  
> out.

I figured the wire format would not be a problem if the version number is  
increased, because older servers could simply respond with an error  
message. Unfortunately this will not work because the client does not  
expect anything to be returned when sending a message type indicating a  
one-way request. Also, new message types expecting a response that does  
not have the older format cannot be properly responded to by older servers.

I guess it is only possible to maintain backward compatibility. Forward  
compatibility would put too much constraints on the possibilities of new  
protocols. The only option for older servers receiving unknown, new  
message types is to close the connection. This would give the client no  
clue as to why the connection is closed, but there is no way for a server  
to communicate the information that works in all situations.

A workaround might be a service/message type that returns the version of  
the protocol implemented by the server. This could be part of the  
protocols, or be implemented as an application service. A client  
connecting to a server can check the version and report immediatly if the  
server supports the minimum version needed.

--
Kind regards,

Johan Stuyts

Re: Redesign of the Java API

Posted by David Reiss <dr...@facebook.com>.
Yeah, this is true.  That is a more application-visible change, though.

Johan Stuyts wrote:
>> One other thing that I forgot to mention is that I would be in favor
>> of adding a new message type for asynchronous calls, even though
>> it would changing the wire format and could be kind of a pain to roll 
>> out.
> 
> This would give the flexility to the client to decide which functions 
> should be invoked in a one-way manner at runtime, instead of deciding at 
> function definition time in the IDL, right? Then the async/oneway keyword 
> can be dropped.
> 
> Would this be acceptable for everyone if the server has no control over 
> which functions are invoked in a one-way manner? If not, the information 
> about being one-way or not must still be recorded in the IDL and must be 
> available to the server so it can enforce the one-way policy.
> 
> --
> Kind regards,
> 
> Johan Stuyts
> 

Re: Redesign of the Java API

Posted by Johan Stuyts <j....@zybber.nl>.
> One other thing that I forgot to mention is that I would be in favor
> of adding a new message type for asynchronous calls, even though
> it would changing the wire format and could be kind of a pain to roll  
> out.

This would give the flexility to the client to decide which functions  
should be invoked in a one-way manner at runtime, instead of deciding at  
function definition time in the IDL, right? Then the async/oneway keyword  
can be dropped.

Would this be acceptable for everyone if the server has no control over  
which functions are invoked in a one-way manner? If not, the information  
about being one-way or not must still be recorded in the IDL and must be  
available to the server so it can enforce the one-way policy.

--
Kind regards,

Johan Stuyts

Re: Redesign of the Java API

Posted by David Reiss <dr...@facebook.com>.
One other thing that I forgot to mention is that I would be in favor
of adding a new message type for asynchronous calls, even though
it would changing the wire format and could be kind of a pain to roll out.

--David

David Reiss wrote:
> I agree with Bryan that we should break these up into separate JIRA issues
> ASAP.  I also think that is important to think of some things in a cross-
> language manner.  For example, using an options object for constructors
> doesn't really require any cross-language consideration, changing the
> TProtocol interface requires some because it is best to keep uniformity,
> and changing the message protocol requires a lot because it is necessary
> to keep interoperability.
> 
>> - A different set of functions for TProtocol so protocol implementations
>> have more flexibility (For example see
>> https://issues.apache.org/jira/browse/THRIFT-110 (Changes to the IDL would
>> still be required to be able to implement a compact format)).
> I think this has to be considered in a cross-language way.  The fact that
> TProtocol has the same interface in each language means that it is much
> easier to code up the same protocol in each language.
> 
>> - Properly supporting optional members of structures.
> I think we can port the C++/JavaBeans code to the normal Java generator
> without redesigning anything.
> 
>> - Removal of the name when writing the beginning of the structure as
>> nobody seems to need this
>> (https://issues.apache.org/jira/browse/THRIFT-8). There is no need to hang
>> on to obsolete constructs and confuse new users.
> This is currently used in the TDebugProtocol in C++ (which produces
> human-readable representations of Thrift structs) and the
> TSimpleJSONProtocol
> in Java which is a lossy write-only protocol that produces easily-consumable
> JSON strings for scripting languages.
> 
>> - Replace base classes with interfaces so implementations that want to do
>> things differently do not have to extend the base class awkwardly. For
>> example: TProtocol and TServer.
> +1
> 
>> - Refactoring of strange constructs in the current API. For example: the
>> 'getTransport(TTransport)' method of TTransportFactory is used as a
>> transport transformer in addition to being used as a factory. When used as
>> a factory method the parameter makes no sense.
> Yeah, I think this is just poor naming.  The TTransportFactory interface
> is used to give us a uniform way of wrapping a transport.
> 
>> - Remove the Client and Processor classes from generated code of services
>> so server and client implementations have more freedom concerning how
>> (service and) function selection information is communicated and
>> processed, and how I/O is handled. See below.
> I don't think that these need to be removed.  They are the most common use
> case by far, but it is completely possible to replace them.
> 
>> - Add an interface to the generated code and add support classes for doing
>> asynchronous calls (i.e. support for sequence IDs). See below.
> This can be done without changing any of the existing interfaces.
> 
>> - Drop the many constructors of a number of classes and replace them with
>> a single constructor taking an options object.
> I'm fine with this.
> 
>> - Drop the 'T' prefix of types as this is not customary in Java.
> As I said when this was suggested for Ruby, I think that the T
> prefix makes it easier to import classes without name collisions and
> distinguishes specific interfaces like TProtocol from generic names
> like "Protocol" or "Binary".
> 
>> Another example that could be built is a client that requests the mapping
>> of (services and) functions to IDs from the server, so invocation of a
>> particular function does not require the sending of the (service and)
>> function names. Instead a few bytes are all that is needed to select a
>> function. This is very difficult to do now because the Client and
>> Processor classes have control over the information of the message being
>> sent.
> This is something that we discussed a few months ago when we had a meeting
> about creating a more compact protocol.  It think the generic term we used
> to describe it was "out of bad exchange of IDL information".  I think it
> is a great idea, but it has to be implemented cross-language.
> 
>> Drop transports
>> ===============
>> All servers currently require a transport, but the internal workings of a
>> server are closely tied to a specific transport. Why have servers work
>> with wrappers around sockets instead of working with sockets directly?
> This is not the case.  For example, the TNonblockingServer in C++ accesses
> sockets directly (via libevent) and hands TMemoryBuffers to the Processor.
> The purpose of the TServerTransport is to make it easier to implement
> servers that are less I/O-aware (like the TThreadPoolServer) in a uniform
> fashion.
> 
>> The only thing that needs to be handled is 'TFramedTransport' because this
>> is a decorator. In my opinion it may be better to implement it as a
>> protocol decorator which frames messages.
> I disagree.  Having it as a transport means that it works across protocols
> and that it can be handled at a lower level.
> 
>> Asynchronous interface
>> ======================
>> (Does anyone have a better name than 'asynchronous functions' so the
>> 'async' keyword and sequence IDs cannot be confused?)
> I've thought a lot about this and I haven't been able to come up with
> anything good.  See https://issues.apache.org/jira/browse/THRIFT-136
> 
>> The extra layer of transports around I/O streams seems redundant to me.
> I would be open to dropping the Transport interface in favor of something
> built into Java, but I am not able to find anything that supports both
> input and output.  For example, it looks like java.net.Socket extends
> Object and implements no interfaces.
> 

Re: Redesign of the Java API

Posted by Johan Stuyts <j....@zybber.nl>.
> This is fine, as long as wire-compatibility is not broken.

I agree that the current wire format for single-service implementations  
must be kept.

But for multiple-service communication the wire format will be (slightly)  
different, so clients written for single-service servers will not be able  
to communicate with the multiple-service servers. The same holds for  
multiple-service clients and single-service clients. Because a new wire  
format is introduced it could also be extended with the following  
possibilities if required:
- combining service and function selection in a single message instead of  
using two messages
- a flag to indicate sequence IDs are not applicable
- out-of-band exchange of IDL information so less data has to be sent in  
requests

Other ideas that people might have, could be supported by the new wire  
format too.

Besides the wire format, whether synchronous or asynchronous communication  
is used also determines which clients can communicate with which servers.  
It is possible for a synchronous client to talk to a synchronous server  
using sockets, servlets, etc., but a synchronous client would never be  
able to talk to an asynchronous server, because what is expected by the  
client and what is sent by the server do not match.

I want to prevent that a lot of clients and servers will be created that  
won't be able to talk to each other just like everybody else does.  
Therefore the supported scenario's should be documented:
- the request wire format
- the role of sequence IDs
- when and in what order messages are sent
- the response wire format

I believe currently the following scenario is known:
- synchronous with a single service per channel
   - request: current wire format
   - sequence IDs not used
   - each request will lead to a corresponding response before next request  
is handled by the server (except for one-way functions)
   - response: current wire format

The following scenario can easily be added:
- asynchronous with a single service per channel
   - request: current wire format
   - sequence IDs are used
   - the server accepts many requests simultaneously, and responses will  
appear on the return channel in any order (except for one-way functions)
   - response: current wire format

I would like to be able to use multiple services over a single channel, so  
this would add another two scenarios:
- synchronous with multiple services per channel
   - request: new wire format for the message/header
   - sequence IDs not used
   - each request will lead to a corresponding response before next request  
is handled by the server (except for one-way functions)
   - response: current or new wire format depending on possibilities  
implemented
- asynchronous with multiple services per channel
   - request: new wire format for the message/header
   - sequence IDs are used
   - the server accepts many requests simultaneously, and responses will  
appear on the return channel in any order (except for one-way functions)
   - response: current or new wire format depending on possibilities  
implemented

I can't remember if there were feature requests or improvements for which  
other scenarios are needed.

-- 
Kind regards,

Johan Stuyts

Re: Redesign of the Java API

Posted by David Reiss <dr...@facebook.com>.
> I would like for clients and servers to be able to handle requests
> anyway they like. Handling a request consists of the following parts and
> how and when these parts are executed should be flexible:
> - reading the request message header
> - asking the function to read its parameters from the input protocol
> - executing the function
> - writing the response message header (for success and failure)
> - asking the function result to write itself to the output protocol
This is fine, as long as wire-compatibility is not broken.

> Why does the way in which you handle asynchronous calls in one language
> have to resemble how you implement it in other languages? I think we
> should design the asynchronous call API for each language separately so
> it feels natural to developers using that language. Also some languages
> might provide native constructs for asynchronous calls not available in
> or widely different from other languages.
That's fine.  I thought you meant to standardize it across languages when
you said:
" Each client implementation has to provide its own mechanism now. It would
" be nice if Thrift provided standard interfaces (for polling, notifications
" or both) for handling asynchronous calls.

Re: Redesign of the Java API

Posted by Johan Stuyts <j....@zybber.nl>.
> I disagree with this.  The processor provides a simple interface for
> selecting a function to call, deserializing its arguments, and
> serializing its return value.  It implements a part of the protocol,
> so replacing can potentially break wire-compatibility.  I don't think
> that it is a component that should be replaced lightly.

It provides only one way of processing a request, and most of the  
protocol-related logic is encapsulated in the parameters and the result,  
and their wrappers. The rest of the logic is duplicated in each processor  
and not very complicated. Reimplementing this logic once for each of the  
few client and server implementations, and keeping the implementations in  
sync is not a big burden in my opinion. The added benefit of moving the  
logic to the client and server implementations is that bug fixes do not  
require regeneration of existing code.

I would like for clients and servers to be able to handle requests anyway  
they like. Handling a request consists of the following parts and how and  
when these parts are executed should be flexible:
- reading the request message header
- asking the function to read its parameters from the input protocol
- executing the function
- writing the response message header (for success and failure)
- asking the function result to write itself to the output protocol

> I meant that this could be added in addition to the current synchronous
> interface.  The problem with having a "standard" interface for  
> asynchronous
> calls is that every language has a different way of expressing callbacks
> and asynchronous I/O.  This doesn't mean that we shouldn't try to present
> a reasonably uniform API, but it does mean that it is a fairly ambitious
> cross-language project.

Why does the way in which you handle asynchronous calls in one language  
have to resemble how you implement it in other languages? I think we  
should design the asynchronous call API for each language separately so it  
feels natural to developers using that language. Also some languages might  
provide native constructs for asynchronous calls not available in or  
widely different from other languages.

> These are both possibilities (and I think TProtocol already supports  
> input
> and output transports).  The downside is that it eliminates the nice
> property that you have just one object that manages all of your  
> communication
> with the other side.

The current code already supports separate protocol objects for input and  
output, you never use functions for reading and writing at the same time,  
and I see two responsibilities: input and output. From a design point of  
view I would use two types. Anyway, it is not a big issue. Both ways will  
work fine.

-- 
Kind regards,

Johan Stuyts

Re: Redesign of the Java API

Posted by David Reiss <dr...@facebook.com>.
> I do feel however that uniformity across languages is less important.
> [...]
> People working on multiple languages might object though.
I do. :)

>>> - Remove the Client and Processor classes from generated code of 
>>> services
>>> so server and client implementations have more freedom concerning how
>>> (service and) function selection information is communicated and
>>> processed, and how I/O is handled. See below.
>> I don't think that these need to be removed.  They are the most common 
>> use
>> case by far, but it is completely possible to replace them.
> 
> It just does not feel right to me where this code is located now. The 
> processing can differ significantly between implementations. Providing one 
> method of request processing in the generated code is confusing. Client 
> and server implementors might hesitate to ignore the code and write their 
> own request processing, because they feel that would be like working 
> against the framework.
> 
> Also if improvements to the request handling have to be made, all 
> generated code has to be regenerated. If the code is moved to the client 
> and server implementations only the library needs to be upgraded and all 
> deployed code benefits.
> 
> To be able to replace Client and Processor other interfaces and classes 
> are needed (i.e. the Service and Function types I described earlier). 
> Again I feel it would be confusing if the generated code contained both 
> Client and Processor, and Service and Functions.

I disagree with this.  The processor provides a simple interface for
selecting a function to call, deserializing its arguments, and
serializing its return value.  It implements a part of the protocol,
so replacing can potentially break wire-compatibility.  I don't think
that it is a component that should be replaced lightly.

>>> - Add an interface to the generated code and add support classes for 
>>> doing
>>> asynchronous calls (i.e. support for sequence IDs). See below.
>> This can be done without changing any of the existing interfaces.
> 
>  From the perspective of a caller of a function it does not look this way. 
> How do I sent a request for which I either:
> - poll for the result, or
> - get notified by an event.
> 
> Each client implementation has to provide its own mechanism now. It would 
> be nice if Thrift provided standard interfaces (for polling, notifications 
> or both) for handling asynchronous calls.

I meant that this could be added in addition to the current synchronous
interface.  The problem with having a "standard" interface for asynchronous
calls is that every language has a different way of expressing callbacks
and asynchronous I/O.  This doesn't mean that we shouldn't try to present
a reasonably uniform API, but it does mean that it is a fairly ambitious
cross-language project.

>>> The extra layer of transports around I/O streams seems redundant to me.
>> I would be open to dropping the Transport interface in favor of something
>> built into Java, but I am not able to find anything that supports both
>> input and output.  For example, it looks like java.net.Socket extends
>> Object and implements no interfaces.
> 
> What about using 'InputStream' and 'OutputStream'? A protocol can be given 
> the streams which it will read from and write to directly.
> 
> I think it is even possible to split protocol into two interfaces: 
> InputProtocol and OutputProtcol.
These are both possibilities (and I think TProtocol already supports input
and output transports).  The downside is that it eliminates the nice
property that you have just one object that manages all of your communication
with the other side.

--David

Re: Redesign of the Java API

Posted by Johan Stuyts <j....@zybber.nl>.
> I agree with Bryan that we should break these up into separate JIRA  
> issues
> ASAP.  I also think that is important to think of some things in a cross-
> language manner.  For example, using an options object for constructors
> doesn't really require any cross-language consideration, changing the
> TProtocol interface requires some because it is best to keep uniformity,
> and changing the message protocol requires a lot because it is necessary
> to keep interoperability.

Okay, as soon as there is consensus that an issue is worth addressing I  
will create a JIRA issue for it.

I agree that message protocol changes should only be considered if it  
provides enough benefit.

I do feel however that uniformity across languages is less important. If  
maintainers of a language are willing to do a bit of extra work to map  
 from the protocol interface of other languages to their language, I  
wouldn't mind having a different protocol interface in that language.  
People working on multiple languages might object though.

>> - A different set of functions for TProtocol so protocol implementations
>> have more flexibility (For example see
>> https://issues.apache.org/jira/browse/THRIFT-110 (Changes to the IDL  
>> would
>> still be required to be able to implement a compact format)).
> I think this has to be considered in a cross-language way.  The fact that
> TProtocol has the same interface in each language means that it is much
> easier to code up the same protocol in each language.

I agree that it is easier if the protocol interfaces are the same across  
all languages, but the new interface won't make it difficult to keep  
languages in sync: instead of writing a field with two methods you write a  
field with one method.

Sure it is possible to do the same thing with a stateful protocol, but a  
stateful protocol is much more complex than a stateless one. Note that if  
you want to verify that the data is always correct the protocol must be  
stateful, because you would have to check that a stop field is not  
followed by other fields in a structure for example. Neither the current  
protocol interface nor the proposed protocol interface will allow this to  
be done in a stateless manner.

>> - Removal of the name when writing the beginning of the structure as
>> nobody seems to need this
>> (https://issues.apache.org/jira/browse/THRIFT-8). There is no need to  
>> hang
>> on to obsolete constructs and confuse new users.
> This is currently used in the TDebugProtocol in C++ (which produces
> human-readable representations of Thrift structs) and the  
> TSimpleJSONProtocol
> in Java which is a lossy write-only protocol that produces  
> easily-consumable
> JSON strings for scripting languages.

Okay, I'll document that the name of the structure that is passed to the  
protocol is meant for human consumption only, and will close THRIFT-8.

>> - Remove the Client and Processor classes from generated code of  
>> services
>> so server and client implementations have more freedom concerning how
>> (service and) function selection information is communicated and
>> processed, and how I/O is handled. See below.
> I don't think that these need to be removed.  They are the most common  
> use
> case by far, but it is completely possible to replace them.

It just does not feel right to me where this code is located now. The  
processing can differ significantly between implementations. Providing one  
method of request processing in the generated code is confusing. Client  
and server implementors might hesitate to ignore the code and write their  
own request processing, because they feel that would be like working  
against the framework.

Also if improvements to the request handling have to be made, all  
generated code has to be regenerated. If the code is moved to the client  
and server implementations only the library needs to be upgraded and all  
deployed code benefits.

To be able to replace Client and Processor other interfaces and classes  
are needed (i.e. the Service and Function types I described earlier).  
Again I feel it would be confusing if the generated code contained both  
Client and Processor, and Service and Functions.

>> - Add an interface to the generated code and add support classes for  
>> doing
>> asynchronous calls (i.e. support for sequence IDs). See below.
> This can be done without changing any of the existing interfaces.

 From the perspective of a caller of a function it does not look this way.  
How do I sent a request for which I either:
- poll for the result, or
- get notified by an event.

Each client implementation has to provide its own mechanism now. It would  
be nice if Thrift provided standard interfaces (for polling, notifications  
or both) for handling asynchronous calls.

>> - Drop the 'T' prefix of types as this is not customary in Java.
> As I said when this was suggested for Ruby, I think that the T
> prefix makes it easier to import classes without name collisions and
> distinguishes specific interfaces like TProtocol from generic names
> like "Protocol" or "Binary".

I think that (except for the case Bryan mentioned) collisions will be very  
rare.

> This is something that we discussed a few months ago when we had a  
> meeting
> about creating a more compact protocol.  It think the generic term we  
> used
> to describe it was "out of bad exchange of IDL information".  I think it
> is a great idea, but it has to be implemented cross-language.

Interoperability is my main objective. I will not implement another  
protocol without consulting other people.

> This is not the case.  For example, the TNonblockingServer in C++  
> accesses
> sockets directly (via libevent) and hands TMemoryBuffers to the  
> Processor.
> The purpose of the TServerTransport is to make it easier to implement
> servers that are less I/O-aware (like the TThreadPoolServer) in a uniform
> fashion.

I probably was too bold in my first statement. I think it is desirable to  
keep the transports to reuse common methods of communication, but feel  
that the transport handling should be pushed more to the background, i.e.  
an implementation detail instead of a core abstraction.

>> The extra layer of transports around I/O streams seems redundant to me.
> I would be open to dropping the Transport interface in favor of something
> built into Java, but I am not able to find anything that supports both
> input and output.  For example, it looks like java.net.Socket extends
> Object and implements no interfaces.

What about using 'InputStream' and 'OutputStream'? A protocol can be given  
the streams which it will read from and write to directly.

I think it is even possible to split protocol into two interfaces:  
InputProtocol and OutputProtcol.

-- 
Kind regards,

Johan Stuyts

Re: Redesign of the Java API

Posted by David Reiss <dr...@facebook.com>.
I agree with Bryan that we should break these up into separate JIRA issues
ASAP.  I also think that is important to think of some things in a cross-
language manner.  For example, using an options object for constructors
doesn't really require any cross-language consideration, changing the
TProtocol interface requires some because it is best to keep uniformity,
and changing the message protocol requires a lot because it is necessary
to keep interoperability.

> - A different set of functions for TProtocol so protocol implementations 
> have more flexibility (For example see 
> https://issues.apache.org/jira/browse/THRIFT-110 (Changes to the IDL would 
> still be required to be able to implement a compact format)).
I think this has to be considered in a cross-language way.  The fact that
TProtocol has the same interface in each language means that it is much
easier to code up the same protocol in each language.

> - Properly supporting optional members of structures.
I think we can port the C++/JavaBeans code to the normal Java generator
without redesigning anything.

> - Removal of the name when writing the beginning of the structure as 
> nobody seems to need this 
> (https://issues.apache.org/jira/browse/THRIFT-8). There is no need to hang 
> on to obsolete constructs and confuse new users.
This is currently used in the TDebugProtocol in C++ (which produces
human-readable representations of Thrift structs) and the TSimpleJSONProtocol
in Java which is a lossy write-only protocol that produces easily-consumable
JSON strings for scripting languages.

> - Replace base classes with interfaces so implementations that want to do 
> things differently do not have to extend the base class awkwardly. For 
> example: TProtocol and TServer.
+1

> - Refactoring of strange constructs in the current API. For example: the 
> 'getTransport(TTransport)' method of TTransportFactory is used as a 
> transport transformer in addition to being used as a factory. When used as 
> a factory method the parameter makes no sense.
Yeah, I think this is just poor naming.  The TTransportFactory interface
is used to give us a uniform way of wrapping a transport.

> - Remove the Client and Processor classes from generated code of services 
> so server and client implementations have more freedom concerning how 
> (service and) function selection information is communicated and 
> processed, and how I/O is handled. See below.
I don't think that these need to be removed.  They are the most common use
case by far, but it is completely possible to replace them.

> - Add an interface to the generated code and add support classes for doing 
> asynchronous calls (i.e. support for sequence IDs). See below.
This can be done without changing any of the existing interfaces.

> - Drop the many constructors of a number of classes and replace them with 
> a single constructor taking an options object.
I'm fine with this.

> - Drop the 'T' prefix of types as this is not customary in Java.
As I said when this was suggested for Ruby, I think that the T
prefix makes it easier to import classes without name collisions and
distinguishes specific interfaces like TProtocol from generic names
like "Protocol" or "Binary".

> Another example that could be built is a client that requests the mapping 
> of (services and) functions to IDs from the server, so invocation of a 
> particular function does not require the sending of the (service and) 
> function names. Instead a few bytes are all that is needed to select a 
> function. This is very difficult to do now because the Client and 
> Processor classes have control over the information of the message being 
> sent.
This is something that we discussed a few months ago when we had a meeting
about creating a more compact protocol.  It think the generic term we used
to describe it was "out of bad exchange of IDL information".  I think it
is a great idea, but it has to be implemented cross-language.

> Drop transports
> ===============
> All servers currently require a transport, but the internal workings of a 
> server are closely tied to a specific transport. Why have servers work 
> with wrappers around sockets instead of working with sockets directly? 
This is not the case.  For example, the TNonblockingServer in C++ accesses
sockets directly (via libevent) and hands TMemoryBuffers to the Processor.
The purpose of the TServerTransport is to make it easier to implement
servers that are less I/O-aware (like the TThreadPoolServer) in a uniform
fashion.

> The only thing that needs to be handled is 'TFramedTransport' because this 
> is a decorator. In my opinion it may be better to implement it as a 
> protocol decorator which frames messages.
I disagree.  Having it as a transport means that it works across protocols
and that it can be handled at a lower level.

> Asynchronous interface
> ======================
> (Does anyone have a better name than 'asynchronous functions' so the 
> 'async' keyword and sequence IDs cannot be confused?)
I've thought a lot about this and I haven't been able to come up with
anything good.  See https://issues.apache.org/jira/browse/THRIFT-136

> The extra layer of transports around I/O streams seems redundant to me.
I would be open to dropping the Transport interface in favor of something
built into Java, but I am not able to find anything that supports both
input and output.  For example, it looks like java.net.Socket extends
Object and implements no interfaces.

Re: Redesign of the Java API

Posted by Johan Stuyts <j....@zybber.nl>.
As my proposal for a redesign was a lot to take in and some people are  
more comfortable with reading code, I have manually rewritten the  
generated code for the 'SharedService' and 'Calculator' services (as  
'SharedService2' and 'Calculator2' respectively), and designed some  
support classes to given an idea of what the code would look like if the  
proposal would be implemented.

Note that the example code is far from complete. There are no working  
client and server implementations. If people want to further explore this  
design I will implement a few clients and servers. I am aware of the  
following issues:
- the API and SPI are incomplete. Some holes are intentional and are easy  
to fill. Actually implementing a number of clients and servers will reveal  
the unintentional holes
- the error handling (communication errors, invalid data, application  
exceptions, etc.) is almost completely missing, and the code that is  
present is probably broken
- there might be inconsistencies in the code of the services because it  
was written manually instead of being generated

Currently code for asynchronous calls using both polling and events is  
included. Depending on the language none, one or both of these methods for  
handling asynchronous calls may be included. I also do not want to imply  
that Java should support both methods. They are possibilities to be  
explored.

The assumption is made that one-way functions are declared in the IDL as  
is currently done, instead of the application being able to call any  
function in a one-way manner by using a different message type as proposed  
by David.

Types in the following packages have to be handled by applications:
- thriftlib.client: interfaces for client-side proxy factories of  
services. Services provide their specific implementations
- thriftlib.client.async.event: interfaces for listening for asynchronous  
responses. Applications have to implement these
- thriftlib.client.async.poll: interfaces for polling for asynchronous  
responses. Client implementations provide their specific implementations
- thriftlib.server: interface for enabling the use of a service by a  
server. Services provide their specific implementations

Types in the following package are used and implemented by client and  
server implementations, and services. Applications never have to use these  
types:
- thriftlib.client.spi: client-side handlers of invocations to be  
implemented by client implementations. Client implementations provide  
their specific implementations. And an interface enabling clients to  
access the result of functions returning structures. Struct result  
wrappers must implement this interface
- thriftlib.common.spi: reusable result wrappers for functions returning  
basic types or void. Used by client implementations and service server  
handlers
- thriftlib.server.spi: interfaces used by server implementations to  
handle services and calls. Services provide their specific implementations

The classes in 'thriftlib.common.spi' can be integrated into the current  
library to reduce the amount of code that needs to be generated for  
services.

-- 
Kind regards,

Johan Stuyts

Re: Redesign of the Java API

Posted by Johan Stuyts <j....@zybber.nl>.
> I appreciate the attention to backward compatibility issues, but I don't  
> think we should be so quick to fork the Java libraries at this stage in  
> the game. While it may not be possible in every regards to every one of  
> your suggestions below, I think in general it would be best if we could  
> apply the improvements to the existing libraries rather than create new  
> ones. This specter of backwards compatibility has been brought up a few  
> times now in regards to big refactors (like changing packages, etc), and  
> I really think while we're in the Incubator, pre-release, we should just  
> refactor what we want to refactor. We're never going to get such an open  
> chance again. That's not to say we shouldn't take steps to ease the  
> transition for people with existing code, but let's find a way that  
> doesn't involve creating a new library and deprecating the old one.

The reason why I would like to start fresh is because I think we can move  
quicker if the old API is dropped. The advantage I see with dropping the  
old API completely is that if the current API is kept, keeping up with  
incremental improvements could become a maintenance nightmare. I  
understand this is an enormous step and of course it should not be taken  
lightly.

>> - Support for changes to the IDL needed to support more formats (e.g.  
>> the compact format) if the IDL is changed.
> It's true that it would be nice if the TProtocol interface was richer,  
> because it would definitely make implementing the compact protocol  
> easier. However, that said, I'm not convinced its necessary. We've  
> established that it can be done with a stateful TProtocol. (We also  
> don't need IDL changes to implement the compact protocol, with the  
> possible exception of extern strings.)

Most things I want to do can indeed be done. But the things I have to  
write feel like kludges instead of solutions that fit naturally into the  
Thrift framework.

What if everything could be simpler so people are more likely to  
contribute and Thrift can grow faster without being held back by a more  
cumbersome API? That is the advantage I want to gain with a redesign.

For example: one change to the IDL might be specifying the range of values  
a member or container element is allowed to have. By passing this range to  
the protocol while writing it is very easy for the protocol to determine  
how to encode a single value or a container of values. Sure, it can be  
done by inspecting the value or all the values in a container, but it is  
so much easier and faster if the information is handed to the protocol.

>> - Properly supporting optional members of structures.
> This is done in the java:beans generator already. I do wonder why anyone  
> would use the non-beans generator at all, though, so you might make the  
> argument that the two paths should be unified.

Okay, I thought that maybe some library classes were involved. Great to  
hear that they are not.

>> - Removal of the name when writing the beginning of the structure as  
>> nobody seems to need this (https://issues.apache.org/jira/browse/ 
>> THRIFT-8). There is no need to hang on to obsolete constructs and  
>> confuse new users.
> This is part of the protocol interface, correct? Are you suggesting that  
> we remove struct names from all of thrift, or just from the Java API? If  
> it's unused, I'm pro-removal everywhere. However, we do have to decide  
> if that is a limitation we want to have.

If nobody needs it, and therefore nobody is going to support it, it can be  
dropped from all languages as far as I am concerned. I created THRIFT-8 to  
get some clarification and got no response so apparently nobody is using  
it. I understand the idea behind it and think that it can work (for some  
languages). At the moment support for it is incomplete and broken. The  
remnants in the classes might confuse new users which should be avoided in  
my opinion.

>> - Remove the Client and Processor classes from generated code of  
>> services so server and client implementations have more freedom  
>> concerning how (service and) function selection information is  
>> communicated and processed, and how I/O is handled. See below.
> Are you sure we should stop generating the code altogether? For most  
> default cases, I doubt people are going to want to reimplement these  
> pieces. I'd be for making the Processor interface clearer and easier to  
> implement outside of code generation, though.

Yes, I want to remove all this code and move the code to client and server  
implementations. I absolutely do not want people to have to implement  
these procedures over and over again. I think the way requests are sent,  
received and processed can differ significantly between implementations  
and therefore the details belong to client and server implementations and  
not to the services themselves.

>> - Drop transports. See below.
> I sort of like the transport abstraction. Not every use of transports is  
> hidden behind a server, after all - Rapleaf does a lot of serializing  
> structures to byte arrays and such. For the case of a transport and a  
> server being intimately intertwined, I would say that there's nothing  
> stopping you from not taking a Transport in the constructor and doing  
> whatever you want internally. The only point at which you need to use a  
> Transport is as soon as you want to rely on the generated code  
> (de)serialization, and at that point you can use the memory based  
> transports. I did something analogous in the TNonblockingServer.

Why would I need a TMemoryBuffer to be able to stream to memory, a file,  
etc.? A protocol could write directly to I/O streams. The extra layer of  
transports around I/O streams seems redundant to me.

The advantage a transport provides over I/O streams is a method to  
completely fill a byte array with input data. This function can easily be  
extracted to a helper function.

The only issue is with TFramedTransport because it is hard to define what  
the transport should frame if it was implemented as a protocol: a message  
(service invocation), a structure (serialization), ...

>> - Drop the many constructors of a number of classes and replace them  
>> with a single constructor taking an options object.
> I see where you're going with this, but doesn't this just mean that you  
> now have to manually code the validation of order and presence of  
> certain parameters in certain situations? Certainly the existing  
> scenario of tons of constructors is overly verbose, but at least it  
> avoids the bugs that would show up if we tried to do it ourself.

No, is should be easy. You just need a single validation function for the  
option object passed in, and call this from the constructor. A simplistic  
example:
static void validate(Options o) {
   if (o.getInputTransportFactory() == null) {
     throw new IllegalArgumentException("Input transport factory cannot be  
'null'");
   }
   if (<some condition>) {
     if (o.getX() == null) {
       throw new IllegalArgumentException("X cannot be 'null'");
     }
   }
   ...
}

The options object needs to have convenience functions so it is easy to  
create a valid instance. For example:
void setTransportFactory(TTransportFactory);
void setInputTransportFactory(TTransportFactory);
void setOutputTransportFactory(TTransportFactory);

I use this pattern all the time and it greatly simplifies my code:
- no management of configuration values in the object itself, i.e.  
everything is moved to the options object;
- a single location containing the validation rules: one method to  
validate whether an options object is correct;
- easy to check if the object is in a correctly configured state in  
methods: just check for a non-null options object (only needed when using  
two-stage construction).

>> - Drop the 'T' prefix of types as this is not customary in Java.
> I'm mostly pro on this one, though there are a few situations that would  
> yield name clashes if we did this to every class (TException ->  
> Exception, for one).

Name clashes with standard classes should be avoided; the less confusion  
the better. Instead of 'T' 'Thrift' can be used then.


In general I would like to say that the reason I posted this is that I  
have a working prototype of a non-Thrift, non-blocking, multiplexing  
server which does not require the use of framing. I am about to build a  
Thrift implementation based on it and I ran into some issues (incomplete  
list):
- the need for a thread-local protocol implementation so a Client or  
Processor can be used from multiple threads;
- the impossibility to detect that a function has the 'async' keyword so I  
cannot start these functions in a background thread and release the  
communication channel;
- the inability to write an efficient header for a multiplexed  
implementation.

If things were less tightly coupled, and the request processing was not  
hardcoded in the services, the implementation would be much easier.

-- 
Kind regards,

Johan Stuyts

Re: Redesign of the Java API

Posted by Bryan Duxbury <br...@rapleaf.com>.
This is a very ambitious proposal! I will comment on specifics  
inline, but let me start by saying that we should probably create a  
lot of separate JIRA tickets for dealing with the ideas raised in  
this issue. As one monolithic blob, it will be too difficult to  
implement and review.

On Sep 9, 2008, at 5:40 AM, Johan Stuyts wrote:

> Hi,
>
> I thought the move from Facebook to Apache packages might be an  
> opportunity to redesign the Java API. Redesigning the API at this  
> stage means that there are no backward compatibility issues: you  
> either use the old or the new packages. A switch can be added to  
> the compiler to choose between code that uses the old or the new  
> packages.
I appreciate the attention to backward compatibility issues, but I  
don't think we should be so quick to fork the Java libraries at this  
stage in the game. While it may not be possible in every regards to  
every one of your suggestions below, I think in general it would be  
best if we could apply the improvements to the existing libraries  
rather than create new ones. This specter of backwards compatibility  
has been brought up a few times now in regards to big refactors (like  
changing packages, etc), and I really think while we're in the  
Incubator, pre-release, we should just refactor what we want to  
refactor. We're never going to get such an open chance again. That's  
not to say we shouldn't take steps to ease the transition for people  
with existing code, but let's find a way that doesn't involve  
creating a new library and deprecating the old one.

>
> Why can a redesign be beneficial?
> - A different set of functions for TProtocol so protocol  
> implementations have more flexibility (For example see https:// 
> issues.apache.org/jira/browse/THRIFT-110 (Changes to the IDL would  
> still be required to be able to implement a compact format)).
> - Support for changes to the IDL needed to support more formats  
> (e.g. the compact format) if the IDL is changed.
It's true that it would be nice if the TProtocol interface was  
richer, because it would definitely make implementing the compact  
protocol easier. However, that said, I'm not convinced its necessary.  
We've established that it can be done with a stateful TProtocol. (We  
also don't need IDL changes to implement the compact protocol, with  
the possible exception of extern strings.)

> - Properly supporting optional members of structures.
This is done in the java:beans generator already. I do wonder why  
anyone would use the non-beans generator at all, though, so you might  
make the argument that the two paths should be unified.

> - Removal of the name when writing the beginning of the structure  
> as nobody seems to need this (https://issues.apache.org/jira/browse/ 
> THRIFT-8). There is no need to hang on to obsolete constructs and  
> confuse new users.
This is part of the protocol interface, correct? Are you suggesting  
that we remove struct names from all of thrift, or just from the Java  
API? If it's unused, I'm pro-removal everywhere. However, we do have  
to decide if that is a limitation we want to have.

> - Replace base classes with interfaces so implementations that want  
> to do things differently do not have to extend the base class  
> awkwardly. For example: TProtocol and TServer.
+1

> - Refactoring of strange constructs in the current API. For  
> example: the 'getTransport(TTransport)' method of TTransportFactory  
> is used as a transport transformer in addition to being used as a  
> factory. When used as a factory method the parameter makes no sense.
+1

> - Remove the Client and Processor classes from generated code of  
> services so server and client implementations have more freedom  
> concerning how (service and) function selection information is  
> communicated and processed, and how I/O is handled. See below.
Are you sure we should stop generating the code altogether? For most  
default cases, I doubt people are going to want to reimplement these  
pieces. I'd be for making the Processor interface clearer and easier  
to implement outside of code generation, though.

> - Drop transports. See below.
I sort of like the transport abstraction. Not every use of transports  
is hidden behind a server, after all - Rapleaf does a lot of  
serializing structures to byte arrays and such. For the case of a  
transport and a server being intimately intertwined, I would say that  
there's nothing stopping you from not taking a Transport in the  
constructor and doing whatever you want internally. The only point at  
which you need to use a Transport is as soon as you want to rely on  
the generated code (de)serialization, and at that point you can use  
the memory based transports. I did something analogous in the  
TNonblockingServer.

> - Add an interface to the generated code and add support classes  
> for doing asynchronous calls (i.e. support for sequence IDs). See  
> below.
> - Drop the many constructors of a number of classes and replace  
> them with a single constructor taking an options object.
I see where you're going with this, but doesn't this just mean that  
you now have to manually code the validation of order and presence of  
certain parameters in certain situations? Certainly the existing  
scenario of tons of constructors is overly verbose, but at least it  
avoids the bugs that would show up if we tried to do it ourself.

> - Drop the 'T' prefix of types as this is not customary in Java.
I'm mostly pro on this one, though there are a few situations that  
would yield name clashes if we did this to every class (TException ->  
Exception, for one).

>
> Removal of Client and Processor
> ===============================
> It is impossible for the client and server implementations to  
> handle services in a generic way currently. The only types  
> available are TProcessorFactory and TProcessor. These types do not  
> provide enough information. For example: for some server  
> implementations it is interesting to know whether or not a function  
> has the 'async' keyword. If a function does have it, the  
> communication channel can be released immediatly instead of being  
> held onto while the asynchronous function is running.
>
> In addition, the assumption that the protocol can be assigned to  
> the classes Client and Processor once, makes it more difficult to  
> implement multiplexing servers (which also need to send the service  
> name in addition to the function name), clients and servers using  
> non-blocking I/O, connection pooling clients, asynchronous calls,  
> etc. It would be much better if client and server implementations  
> have more control over how they want to handle things before  
> passing control to the function implementations.
>
> By only supplying the minimal information about services and  
> functions to client and server implementations, and by passing the  
> protocol as late as possible to function implementations, lots of  
> flexibility is gained. Here is a rough draft of how the API would  
> look like (from the perspective of the server. Information and  
> methods needed for client implementations are missing):
> class Service {
>   Function get(String);
> }
> class Function {
>   boolean isAsynchronous();
>
>   // Throws an exception if function is asynchronous.
>   //
>   // Only reads the structure containing the parameters
>   // using the protocol. Messages are handled by the
>   // server.
>   //
>   // Returns the wrapper around the result.
>   //
>   // Server can decide when to write the result without
>   // having to copy it to a byte array.
>   Base invoke(Protocol);
>
>   // Discards result if function is synchronous.
>   //
>   // Only reads the structure containing the parameters
>   // using the protocol. Messages are handled by the
>   // server.
>   void invoke(Protocol);
> }
>
> Another example that could be built is a client that requests the  
> mapping of (services and) functions to IDs from the server, so  
> invocation of a particular function does not require the sending of  
> the (service and) function names. Instead a few bytes are all that  
> is needed to select a function. This is very difficult to do now  
> because the Client and Processor classes have control over the  
> information of the message being sent.
>
> For the multiplexing server that I want to build having more  
> freedom could mean replacing this request header:
> i32:    version and type
> string: service name
> i32:    sequence ID (unused)
> i32:    version and type
> string: function name
> i32:    sequence ID
>
> With this request header (if I implement the function to ID  
> mapping). This saves (for a 15-character ASCII service name, a 10- 
> character ASCII function name and less than 16384 functions) 42-43  
> bytes per function invocation:
> byte:   version and type
> vint:   function ID (1 or 2 bytes)
> i32:    sequence ID
>
> If I would use one bit of the version and type byte as a flag to  
> indicate sequence IDs are not needed, another 4 bytes could be  
> saved, i.e. only 2-3 bytes would be needed to select a function.
>
> Note that protocols must understand more header types than  
> 'TMessage' for this to work. Maybe the clients and servers must be  
> given the freedom to write the header instead of having a single  
> message type. Not all clients and servers can have their own header  
> format because that would defeat interoperability, instead a number  
> of header formats have to be agreed upon. For example:
> - Current header format for single-service clients and servers.
> - New header format for multiplexed clients and servers with  
> support for:
>   - a function to ID map for more efficient function selection;
>   - indicating a sequence ID is not needed.
>
> Removal of the Client and Processor classes will also remove a lot  
> of duplicate code for handling calls from the generated classes. In  
> my opinion this duplicate code can easily be transformed into  
> generic code in client and server implementations.
>
> Drop transports
> ===============
> All servers currently require a transport, but the internal  
> workings of a server are closely tied to a specific transport. Why  
> have servers work with wrappers around sockets instead of working  
> with sockets directly? Possibilities for server implementation will  
> now be limited by the wrappers instead of allowing the full  
> flexibility of the socket API.
>
> In my opinion a transport is internal to a server. If a server can  
> be implemented in a better way, the thin transport wrapper around  
> sockets should not be a limiting factor. It would be very  
> cumbersome if an API change of a 'TServerTransport' implementation  
> is needed to be able to implement a server differently.
>
> The only thing that needs to be handled is 'TFramedTransport'  
> because this is a decorator. In my opinion it may be better to  
> implement it as a protocol decorator which frames messages.
>
> I don't know how this works out for clients but I think it would be  
> very similar.
>
> Asynchronous interface
> ======================
> (Does anyone have a better name than 'asynchronous functions' so  
> the 'async' keyword and sequence IDs cannot be confused?)
>
> The addition of an asynchronous interface (to support sequence IDs)  
> besides the synchronous one makes it easier to implement  
> asynchronous calls (using sequence IDs). Asynchronous calls need to  
> be handled differently by a client anyway, so it is best to make  
> this distinction clear. For some languages only asynchronous  
> interfaces might be generated. Here is a rough draft of how this  
> would look if polling is used to retrieve the response:
> interface Calculator.IfaceAsync {
>   AsynchronousCall ping();
>   IntAsynchronousCall add(int, int);
>   IntAsynchronousCall calculate(int, Work);
>   // zip() not added because it does not return a result
> }
> interface AsynchronousCall {
>   boolean hasResponseArrived();
> }
> interface IntAsynchronousCall extends AsynchronousCall {
>   int getResult();
> }
> interface StructAsynchronousCall<R> extends AsynchronousCall {
>   R getResult();
> }
>
> An alternative is to use events instead of polling:
> interface Calculator.IfaceAsync {
>   void ping(VoidAsynchronousCompletion);
>   void add(int, int, IntAsynchronousCompletion);
>   void calculate(int, Work, IntAsynchronousCompletion);
>   // zip() not added because it does not return a result
> }
> interface VoidAsynchronousCompletion {
>   void handleResponse();
> }
> interface IntAsynchronousCompletion {
>   void handleResponse(int);
> }
> interface StructAsynchronousCompletion<R> {
>   void handleResponse(R);
> }
>
>
> What do you think? Would a redesign be useful and worth it?
>
> -- 
> Kind regards,
>
> Johan Stuyts