spring-guides/gs-messaging-stomp-websocket

This is confusing

dagnelies opened this issue · 5 comments

dagnelies commented

Hi,

Sorry to bother you, but I wanted to give you some feedback. As a noob, the whole tutorial feels rather contrived and far from trivial. Here are a few suggestions how it could be made more "friendlier".

First, emphasize that it's not raw websockets, but "STOMP" over websockets. Most of us never heard of STOMP. At least a brief introduction of how STOMP works should be provided ...and it would be nice to now if raw websockets are possible.

Secondly, the whole is written upside down. You first write controllers, topic subscriptions, message brokers, endpoints, application destination prefix (do we really need that one?!) without really understanding why, and it's just confusing.

Here as well, an introduction should first be provided. An overview about the flow and the pupose of each "thing", before diving into the code. Ideally with a nice picture, to help understand how it all fits together.

Lastly, the HTML / js example is bloated, the only thing you need would be something like:

<body>
    <button id="connect" onclick="connect()">Connect</button>
    <button id="disconnect" onclick="disconnect()" disabled>Disconnect</button>
    <hr/>
    What is your name? <input id="name" /><button onclick="sendName()">Send</button>
    <hr/>
    <pre id="greetings"></pre>
</body>

Best Regards

dagnelies commented

Lastly, despite it's complexity, it leaves big question marks on how to do simple things because of the STOMP abstraction. How whould you:

  • get a list of connected clients
  • how to perform some sort of authentication
  • how to get "session" data

Using something like raw websockets feels much more trivial:

import javax.websocket.*;
import javax.websocket.server.ServerEndpoint;
    
@ServerEndpoint("/actions")
public class DeviceWebSocketServer {

    @OnOpen
    public void open(Session session) {
    }

    @OnClose
    public void close(Session session) {
    }

    @OnError
    public void onError(Throwable error) {
    }

    @OnMessage
    public void handleMessage(String message, Session session) {
    }
}

...I just wonder if it's well compatible with the rest of spring.

  • 👍2
gregturn commented

You make several good points that the guide could use some keen help.

  • Show a logical flow of how someone would really design this type of layout. (Where people sincerely start when doing WebSockets could vary.)
  • Since we are indeed mixing JavaScript/WebSockets/Java together in one app, more discussion/explanation is clearly warranted.
  • What is STOMP and why would anyone use it is definitely required.

I would even support a brief explanation (perhaps an asciidoctor NOTE?) that explains differences between JSR-356 and using STOMP to accomplish your end goals.

That's because JSR-356 comes with its own quirks. While doing a very simple application, it makes perfect sense and is already provided. But once you expand to a "real" application with different types of messages, JSR-356, IMHO, doesn't scale very well.

That's because you either need to implement multiple endpoints, or you have to implement switching inside the handler methods to deal with the fact you'll probably have different messages aimed at different JavaScript components.

Multiple endpoints is wrong, because the whole idea behind WebSockets is that they're so light, you should only need one for a given client. And switching inside the handler methods is one of those things you want to avoid writing over and over, and thus, you let framework code handle.

(Wouldn't all this fit nicely into an explanation box on the guide, perhaps with links to BOTH parts of the Spring Framework reference docs, the STOMP as well as the JSR-356 bits?)

dsyer commented

There is already a link to the STOMP spec FWIW. But I agree that the guide overall is clunky, and lacks motivation. The use of jquery to set up event listeners seems legit though, so I'm not sure I'd change the HTML/JS much.

rstoyanchev commented

@dagnelies your expectations are somewhat misplaced. These guides are supposed to get you to the point of running something in 15 minutes. It sounds like what you'd like is a tutorial but that's not what this is. There just isn't any room for these kinds of explanation in the given format.

I don't think any extensive change needs to be done. Creating a separate tutorial would make much more sense. That said it could be worth inserting a paragraph to explain that this WebSocket with a sub-protocol on top and that the guide will not explain the details of the protocol. As for links why don't we point to our own reference https://docs.spring.io/spring/docs/current/spring-framework-reference/web.html#websocket.

dsyer commented

I added a sentence.