On 2/21/13 4:06 AM, Joe Walnes wrote:
> I'm on the fence on this one....
>
> In general, I like shorter names, and avoiding duplication.
>
> But... the only problem is that many developers don't even think about
> import statements any more, as the IDE does it automatically and often
> hides them from you. If you ignore the import statements, there's
> little clue that the After class has anything to do with WebSockets.
>
> Maybe just using the 'WebSocket' to the top level Endpoint annotations
> would be enough of a clue? But then that's inconsistent. Hmmm. I'll
> get back on the fence.
Let me see if I can nudge you off :)
In terms of whether the annotation should contain some naming to make
the 'websocket-ness' visible, taking a look across the Java EE specs and
their conventions for annotation naming. As usual, there isn't really a
totally consistent practice :(
But:-
For EJB, CDI, JSF, Persistence, e.g.
http://www.physics.usyd.edu.au/~rennie/javaEE6ReferenceSheet.html
it seems that there is a mix of conventions. Persistence is somewhat on
the side of including the technology name in the annotation somewhere.
EJB does in one regard: @EJB to inject an EJB in some other component),
but mostly doesn't, (@Stateful when defining an EJB). JSF doesn't really
include JSF-ness in its annotations.
JAX-RS tends to use very general naming: @Produces, @Path, with not much
JAX-RS-ness in them.
http://jsr311.java.net/nonav/javadoc/index.html
Servlet seems to have defined a mix of names some general, some very
specific, e.g. 'Web*', 'Http*', 'Servlet*' as in @HttpConstraint,
@WebListener, @ServletSecurity
http://docs.oracle.com/javaee/6/api/javax/servlet/annotation/package-summary.html
So, I'd say overall the other EE annotations are not especially
concerned with including the technology name in them.
So I think its ok if we don't pepper everything with WebSocket* either.
- Danny
>
> -Joe
>
>
> On Wed, Feb 20, 2013 at 7:03 PM, Danny Coward <danny.coward_at_oracle.com
> <mailto:danny.coward_at_oracle.com>> wrote:
>
> 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
>
>
--
<http://www.oracle.com> *Danny Coward *
Java EE
Oracle Corporation