On 2/22/13 6:19 AM, Joe Walnes wrote:
> Ok, I'm nudged. +1
:) Then I see Mark is good with it too, so I'm checking the change into
v013.
So if anyone has other suggestions on annotation naming, please take a
look and speak up soon !
Thanks,
- Danny
>
> 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
> <http://www.physics.usyd.edu.au/%7Erennie/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
>>
--
<http://www.oracle.com> *Danny Coward *
Java EE
Oracle Corporation