Ok, I'm nudged. +1
On Thursday, February 21, 2013, Danny Coward wrote:
> 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>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
>
>