Hi Richard, thanks a lot for having a look at this. > On 11 Sep 2015, at 00:41, Richard Warburton <richard.warbur...@gmail.com> > wrote: > > Thanks a lot for implementing this by the way - I can see that it would be a > useful API for many people.
That's the main problem (as usual though). Different people have different needs. For some a mere Java version of W3C WebSocket API [1] would be just enough. Others will require an a lot more sophisticated API with the ability to access individual frames, rearrange them in an output queue, etc. And to do everything in a fully asynchronous fashion with non-blocking back-pressure. Some would like to have an SPI for extensions. The list can be continued... In my opinion, it would be very-very hard, if at all possible, to please everyone given the set of requirements above. > 1. Consistency. It feels a bit inconsistent that the "start builder" method > name for HttpClient is create() and "end builder" method name is "build", > whereas for websockets the start is "newBuilder" and the end is "create". > This is because > > a. that they're different, and > b. that create() is the start for one, and the end for the other. Completely agree. > 3. Perhaps I'm missing something here, but I don't see the value of the > "Outgoing" abstraction. It seems like it would be simpler and lower > allocation to just having multiple sendAsync methods, whilst the outgoing > class adds unnecessary complexity to the API. Outgoing has several purposes. First of all, it separates construction of data from sending data. Indeed, if we remove it, WebSocket will have to have many different sendAsync variants. Secondly it hides the notion of fragmentation. Thus not exposing a user to many protocol-level rules and restrictions (e.g. interjection, size restrictions, "non-fragmentability" of control frames, etc.) Basically, Outgoing says: give me any complex data, I will figure out how to send it for you. Obviously, this simplicity comes at a cost of reduced flexibility. The bottom line is Outgoing will probably have to go because of the criticism. > 4. In a similar vein requiring API users who are consuming data to extend the > Incoming class also seems to be a negative. An alternative would be to offer > the ability to register multiple callbacks with functional interfaces for > receiving data. The advantage of this approach is that it means that users of > the API don't have to force their class hierachy to fit into the API. They > can just write it independently and use method references or lambdas to wire > up the callbacks for receiving data. Yes, it looks like some people do prefer to have this style of APIs. Please understand, I don't want to start a discussion on whether it's right or wrong. In my opinion it all depends on the API and use cases. For this API I would prefer to have (if it's possible) full-fledged, rich types with many methods (with adequate method names that fit the domain), rather than a bunch of separated consumers, suppliers, functions or what have you. Thanks. -Pavel
