Hi folks,
I've had a good look at our annotation naming in the API, and have some
proposals to make it more consistent and clear.
In general we are not prefixing WebSocket* to our classnames, yet we do
so to the annotations. I think this is somewhat inconsistent - and also
makes the annotation names long ! We also use @WebSocketEndpoint for
server endpoints, and @WebSocketClient for client endpoints, so
'endpoint/client' naming pair. In the API 'endpoint' is used both for
client and server endpoints, and 'client/server' naming to distinguish
the two kinds when we need to - another inconsistency between the
classes and annotations, and one that I've noticed new users of the
annotations have been confused about.
So for the class-level annotations, I'd like to propose the following
renames
@WebSocketEndpoint -> @ServerEndpoint
@WebSocketClient -> @ClientEndpoint
For the method level websocket lifecycle annotations, I'd like to remove
the WebSocket* prefix, and leverage the 'onXXX' nomenclature both of our
own Endpoint API, and also the w3c javascript API. So
@WebSocketOpen -> @OnOpen
@WebSocketMessage -> @OnMessage
@WebSocketError -> @OnError
@WebSocketClose -> @OnClose
and finally,
@WebSocketPathParam -> @PathParam
all the annotation attribute names would remain the same.
Explicitly, here's an example before/after
import javax.websocket.server.*;
import javax.websocket.*;
@WebSocketEndpoint("/foo/{level}")
public class Before {
@WebSocketOpen
public void init(Session s, EndpointConfiguration ec) {}
@WebSocketMessage
public void handle(String s, @WebSocketPathParam("level")
String level) {}
@WebSocketError
public void handleError(Throwable t) {}
@WebSocketClose
public void bye(Session s) {}
}
import javax.websocket.server.*;
import javax.websocket.*;
@ServerEndpont("/foo/{level}")
public class After {
@OnOpen
public void init(Session s, EndpointConfiguration ec) {}
@OnMessage
public void handle(String s, @PathParam("level") String level) {}
@OnError
public void handleError(Throwable t) {}
@OnClose
public void bye(Session s) {}
}
--
<http://www.oracle.com> *Danny Coward *
Java EE
Oracle Corporation