[jsr356-experts] Re: Updated Spec: v005: Close to EDR

From: Jeanfrancois Arcand <jfarcand.oss_at_gmail.com>
Date: Thu, 20 Sep 2012 18:45:16 -0400


some comments on the specification (catching up, so ignore what have
already been discussed in the list :-))

  * Section 3.1.5 "In particular, they may wish to intervene more in the
    handshake process. For example,
    they may wish to use Http cookies to track clients, or insert
    application specific headers
    in the handshake response"
      o The Javascript API doesn't allow to read the response's header
        after an hanshake. So I'm sure sure allowing an application to
        do that is the right way to go.
  * Section 4.2: "The decorated method must either have no parameters or
    have a single parameter that is a Session object."
      o Why only Session? Although the JavaScript API isn't allowing to
        set any custom header, this is still possible to pass query
        strings to the URL. Hence it would be convenient to be able to
        see the Request information from an onOpen method.
          + we should support getQueryString/getParams etc. on the
            Session API
  * Section 4.2.1 : "The decorated method must either have no parameters
    or have a single parameter that is a Session object."
      o getCloseReason on Session doesn't looks corect. What will be the
        returned value when the session is active? I think the
        CloseReason should be passed to the @WebSocketClose method
        instead of being intermixed with the session API.


  * Any reason to use RemoteEndpoint instead of WebSocket as the class's
    name? I found it confusing, e.g we don't call a RemoteSocket a
    Socket in java.io ;-)
  * Should the HanshakeRequest by typed so getSession() returns the type
    instead of Object? So we don't have to call instanceof to make sure
    we are getting the right Session object at runtime.
  * Endpoint.onClose should pass the close closing code IMO so an
    application can acts the same way the JavaScript API allow, do
    something based on a close code. Live above, I don't think mixing
    close status inside the Session is the right way to go.
  * ClientContainer.getActiveSessions(): This needs to be clarified as
    Session may become invalid at any moment.
  * Do we really need the Decoder.willDecode(..) API? Should we throw an
    exception instead when the decode gets called?
  * Session.getMessageHandler() must return a Set<MessageHandler>

In general all the APIs aren't fluid and never return itself ... for
example, the Session interface could return itself instead of 'void' all
over the place. Would be nice to be able to chain calls


That's cosmetic, I know.

-- Jeanfrancois

On 12-09-14 7:44 PM, Danny Coward wrote:
> Hi folks,
> I've updated the specification document and API again this week. I'm
> still looking for review comments. This week only some smaller
> changes, the API tweaks arising from our work on the reference
> implementation (see below).
> The v005 API is in the source repository, under the v005 branch.
> http://java.net/projects/websocket-spec/sources
> spec document and javadoc here:-
> http://java.net/projects/websocket-spec/downloads/directory/Spec%20javadoc%20Drafts/v005
> Changes
> - added to the security chapter in the specification.
> - bolstered up some of the javadoc here and there, esp annotations
> - added missing constructors on DecodeException
> - add WebSocketError annotation, mirroring other lifecycle annotations.
> We have had a number of drafts and revisions now, and I think with one
> more round of review next week and comment we are almost ready for
> Expert Draft review. Many of you will know all about this stage, but
> the main point is that it allows us to get review from a wider
> audience. Not everything has to be finished, or complete. But I think
> we have a lot of our content in place, and with another round of
> review, it will be in good enough shape for new readers to give us
> good feedback on what is there.
> We have made the RI project public now: its at
> http://java.net/projects/tyrus/ if you want to take a look. Still a
> work in progress, but it is tracking the v003 API.
> Cheers,
> - Danny
> --
> <http://www.oracle.com> *Danny Coward *
> Java EE
> Oracle Corporation