[WEBSOCKET_SPEC-9] API Usability: Consider API renaming, minor refactorizations for usability Created: 21/Sep/12  Updated: 23/Feb/13  Resolved: 23/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Minor
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v013


In particular, Session and FrameBuilder, configurations.


Annotations have long names.

Session is perhaps too general. Session/WebSocketSession/Connection/Conversation.

Feedback: I think the Session class would be more intuitively served by calling Connection because that's what it seems to captures between the two peers. There is no message bag to store properties (no need to have it) to make this class look like a session. All other methods on this class seem more like properties of a connection rather than a session.

Split RemoteEndpoint send functionality into a handful of specialized RemoteEndpoints, each with a different mode:-

one for basic whole message sending
one for streaming message sending
one for async message sending
one for batching, which could be optional.

DefaultServerConfiguration should be DefaultServerEndpointConfiguration
ditto client config class.

private static String CLIENT_CLASSNAME_PROPERTYNAME = "websocket.clientcontainer.classname"; and WebSocketContainer.getClientContainer(). Should not need to be client specific -> getContainer() ?

IOException on client connect APIs for IO errors, deployment error would then only be for badly formed endpoints.

Annotation names: too long ? Need WebSocket in all of them ? Better distinction between client and server annotations ?

Refactor standard handshake header names into one separate util class.

ServerApplicationConfiguration should be renamed: According to the spec, there may be more than one ServerApplicationConfiguration classes in the application. In that case ServerApplicationConfiguration should be renamed to something else, as it is not application configuration. We need a name that distinguishes it from endpoint configurations, yet there may be some confusion with the name Application causing people to think there can only be one per application package, which is not true.

Comment by dannycoward [ 23/Feb/13 ]

Some of these have been fixed in v013, some will not be fixed. Here's a tally of what changed

Annotations have been renamed to address the name length and client/server distinction.
RemoteEndpoint has been refactored
Session is the same
The configuration API has changed, plus there is a separate issue tracking some suggestions for renames on the new API
Client connect APIs now include IOException and DeploymentException
ContainerProvider now uses the ServiceLoader mechanism, not a system property

Generated at Sun Oct 04 22:20:02 UTC 2015 using JIRA 6.2.3#6260-sha1:63ef1d6dac3f4f4d7db4c1effd405ba38ccdc558.