jakartaee / jakartaee/websocket

Clarify concurrency of Basic and Async messaging

Open
#288 2 comments 1 reaction 0 assignees View on GitHub
API (Both) enhancement
Dominant language
Java
Stars
78
Forks
47
Avg merge
1h 32m
Merged PRs (30d)
1

Description

The Javadoc for `RemoteEndpoint.Basic` has the following text

> If the websocket connection underlying this RemoteEndpoint is busy sending a message when a call is made to send another one, for example if two threads attempt to call a send method concurrently, or if a developer attempts to send a new message while in the middle of sending an existing one, the send method called while the connection is already busy may throw an java.lang.IllegalStateException.

This was originally on `RemoteEndpoint` but after the refactoring to `Basic` and `Async` was performed the text only appeared on `Basic`.

There are several issues.

1. The use of MAY
By defining that an exception "may" be thrown in this case, the user of this API has to code to handle this case since an exception "may" be thrown. This results in unnecessary work if the implementation opts not to throw an exception.
I suggest that this instance of "may" is changed to either "must" or "must not". I have no strong preference for either.

2. Inconsistent concurrency requirements.
It is not clear if this "no concurrent send message calls" requirement applies to `Async` or not. This should be clarified.
Note that the TCK suggests that this requirement does not apply to `Async`.
I suggest that `Basic` and `Async` follow the same rule and either both allow concurrent calls or both do not.

If concurrent calls to send message methods are allowed then that raises the question of how to handle them since they are not permitted on the wire (ignoring the multiplexing extension). Do subsequent messages get buffered until the first completes? If yes, how is that buffer managed? What prevents a OOME if messages are sent slower than the application writes them? Where is the back pressure? Alternatively - and perhaps simpler to implement - do subsequent calls block until the previous call completes? In this approach are the blocked threads placed in a FIFO queue?

Contributor guide

Open the contributing guide

Research direction

Compare the Javadoc for RemoteEndpoint.Basic and RemoteEndpoint.Async with the TCK behavior mentioned in the issue. Determine and document one consistent rule for concurrent sends, including the required handling of overlapping calls and the meaning of the exception wording. Done means the API documentation and related expectations no longer leave Basic and Async behavior ambiguous.

Written by the indexing model from the issue text.

Assessment

Tech stack
java
Domain
api, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.