Another question that has come up as people look at the API and implement it is the issue of precedence when an endpoint has multiple MessageHandlers. I wrote up a little proposal that seeks to define how the container is supposed to select which of potentially numerous of MessageHandlers to callwhen a web socket message arrives.
Let me know if you have other suggestions,
Each web socket message is handled by at most one message handler
Messages that are unhandled result in calls to onError/@WebSocketError callbacks, so developers can always know if a message does not get handled
Developer provided decoders are chosen before platform decoders.
If a decoder fails, the error is delivered and no more decoders are attempted.
MessageHandlers for custom objects (provided a Decoder exists) are chosen over the basic MessageHandlers
1. a whole string message arrives
a) if there is an MessageHandler.AsyncText handler - call it once with the whole string and stop, otherwise continue...
b) if there is an MessageHandler.CharStream handler - call it once using the whole string as the source and stop, otherwise continue...
c) if there is a MessageHandler.DecodedObject<T> where T is not String, then try to find a Decoder.Text<T> or a Decoder.TextStream<T>. Look, in order, through developer provided ones (single list, may contain both Text and TextStream types). Then look through platform provided ones. Use the first match to decode it. If the decode completes without error, call the MessageHandler and stop, if not, call the onError/@WebSocket method with the decode exception and stop. If there is no suitable Decoder, continue....
d) if there is a MessageHandler.Text handler handler, call it, using the first developer provided Decoder.TextStream<String> or Decoder.Text<String>, if any.
e) If the message is still unhandled, call back on the onError/@WebSocketError method. We may need a new exception type for Unhandledmessages.
2) a whole binary message arrives: use analogous process to 1)
3) the first piece of a chunked string message arrives.
a) if there is an MessageHandler.AsyncText handler - call it repeatedly until all the message has arrived and stop, otherwise continue..
b) if there is an MessageHandler.CharStream handler - call it with a Reader linked to the incoming parts, and stop, otherwise continue..
c) if there are MessageHandler.Text or MessageHandler.DecodedObject handlers, wait for all the string pieces to arrive, building the whole message as you go (subject to the buffer limit defined on the *Container). If the buffer limit is exceeded call the onError/@WebSocketError method on the endpoint. Otherwise, using the whole message, jump to the analogous steps for 1c), d) and e) to process the complete message.
4) the first piece of a chunked binary message arrives: use analogous process to 3)
[jsr356-experts] Call precedence of multiple MessageHandlers