Perhaps public Map<String, String> getURISegments() on Session.

Use an annotation for automatic deployment of subclasses of Endpoint (possibly instead of publishEndpoint)
Use web socket annotations on the client side.

http://docs.oracle.com/javase/7/docs/api/java/nio/channels/CompletionHandler.html

One counter argument is that we'd like only to use SAM types in the API so that it is easy to write lambdas when we can rely in JDK 8. Will check into whether there are plans for this JDK interface to evolve to be 'lambda-ready'.

Allow the ServerEndpointConfiguration to match on URI-templates by default just like annotations do.

Also expose the path segments on the Session object (Martin's request).

For example, if there is an AsyncText, Text handlers added to the session - which gets called ?

What happens if the incoming message is async and there is only a Text handler ? (should specify).

@WebSocketEndpoint("/hello")
public class HelloServer {
@WebSocketMessage
public void processGreeting(String message)

{ .. }

@WebSocketMessage
public void processCommunication(String message) { .. }

}

both get called ? What order ? Sequentially on same thread ?

Can a POJO annotate multiple methods with the same annotation more than once, for the other annotations too @WebSocketOpen and so on ?

These were reported by Mark Thomas - thankyou Mark.

1. DecodeException / EncodeException
Parameter ordering is inconsistent
(ByteBuffer, String) vs. (String, Object)

2. DefaultClientConfiguration
getExtensions() returns null
setExtensions() has a parameter of preferredExtensions
(should probably be extensions)

3. CloseReason
No accessor for closeCode
No accessor for reasonPhrase

4. Methods in public interfaces do not themselves need to be declared
public. (style issue / choice)

5. Endpoint
Parameter ordering is inconsistent
onClose(Session, CloseReason) vs. onError(Throwable, Session)
Parameter naming is inconsistent s vs. session

6. Generics
API uses raw types in a few places.

7. Session
s/getRemoteL/getRemote/

Otherwise the implementation can't use it !

See, for example, the Guava project

http://docs.guava-libraries.googlecode.com/git/javadoc/com/google/common/util/concurrent/ListenableFuture.html

Its not necessary, and it would also make this spec consistent with JAX-RS.

There are several statements in the TCK license that appear to conflict with the following requirement from JCP 2.8:

"TCK license terms must permit implementors to freely and publicly discuss the testing process and detailed TCK test results with all interested parties."

Section 4.3:

• why are other annotations subsections of this section (i.e. Open is 4.3, but close and error and message are 4.3.1, 4.3.2, 4.3.3)
• you keep mentioning @WebSocketPathSegment - I guess you mean @WebSocketPathParam

Looks like RemoteEndpoint has to be. How about Session (yes). Configuration and container APIs ?

We already have threading definitions for Endpoint and MessageHandler.

May need to define something about container created callback threads for onMessage() and how they interact with callback threads for (async) sends.

Then the user knows about the failure cases.

We should probably look to JAX-RS for the list of default encoders and decoders it would be good to support in the API. For example (this is a subset of what JAX-RS supports):-

all Java primitive types
and their class counterparts
and collections thereof.

And we will need to define how they are overridden by application provided encoders and decoders.

Sections 4.1.2 and 4.1.3 will need updating in addition to the javadoc in various places.

In particular, the different categories of error conditions and where they are handler (container/application).

Also, why is EncodeException a checked exception instead of a runtime one ?

An application might need to maintain context across multiple messages from an endpoint. The Session interface should allow attaching arbitrary objects.
This is similar to HttpSession setAttribute(), getAttribute() etc. methods, but isolated from HttpSession.

The Session interface can just provide access to a Map object :
Map<String, Object> getAttributes()

It looks like we cannot convert Frame's text data to String since text frame might include a partial UTF-8 sequence. So the returned Frame.Data.Text#getText() can only return partial String, and the partial bytes from the UTF-8 char need to be combined with the next frame's bytes. So I propose to remove Frame.Data.Text#getText() and expose only byte types in the API.

Also, instead of using so many sub-types(for e.g Frame.Data.Text.Continuation), the type hierarchy could be flattened esp if everything is dealt with bytes for frames. I don't see much value for having a separate Continuation type compared to an additional method to check whether the frame is last one or not.

As summary. Some people think we should not have programmatic APIs for creating endpoints.

• Does the order of @WebSocketPathParam in the method matters ? Can it be the last one, first one, in the middle ?

• Same section, what is the usecase for parameter injection in lifecycle methods ? Those are implicitly called by the container anyway and never explicitly invoked as part of a URI.

• When @WebSocketPathParam is used, we should also define integration with Bean Validation. This will allow to define constraints on the bean when data conversion needs to happen.

rather than combined them into one.

This was Greg's suggestion, and although it was added in an earlier draft than EDR, it appears to have dropped back out when we moved the RI to a new repo.

We will split out the methods as suggested.

In particular:

• Seems the following sentence: "The container may not invoke the close method on an endpoint
  until the open method has either completed, or the container has determined that it will
  not wait until it has completed and has removed it from service [WSC-39]."
  implies/could be rephrased to "The container may or may not wait until the onOpen method completes before calling onClose."
  Is that the intended implication?
  How about onError? Is it called before onClose? May onClose be called before onError completes? May onError be called before onOpen completes? Am I not guaranteed to get onOpen, onError and onClose calls for one single session on the same thread?

allow things like

@WebSocketMessage
public void handleMethod(String message, @WebSocketPathParameter("level") Integer i) {
XXXX
}

or any of the usual other that map easily to the subset of strings that are allowed to be URI path segments: java primtitive types, etc..

Check this against the allowable types in JAX-RS.

As described.

The motivation is to allow people to build anything they would like on top of it.

(I think the API already allows this, but I will check. Also, I would like people to be able to use lamdas for all the message handlers. This requires them to be SAM.)

Currently the spec defines there is one endpoint instance per URI per VM. So the endpoint instance is application scoped.

Consider using one instance of an endpoint per client. This simplifies the threading model, but removes the ability of the developer to use the endpoint to share state that is common to multiple requests.

The developer needs to be able to hold application-wide state AND session state, so this is related to the issue of having a place to associate user data with the session.

The JAX-RS spec defines its endpoint instances to be request scoped by default, but this can be overridden so that they are application scoped to.

If we make the endpoint a CDI managed bean, then we can allow different modes.

There is no reliable way to tell if the session is active or not without doing an expensive ping.pong.

SO is this method really useful ?

Should it be: 'is it not inactive' ?

Is there a better way to express this ? hasBeenClosed() ?

Also, container.getActiveSessions() - the useful case is tracking the active sessions per endpoint, not per container.

Will this work in the distributed container ?

Update to javadoc for

DefaultClientEndpointConfiguration/ ClientEndpointConfiguration.getPreferredSubprotocol getPreferredExtensions
DefaultServerEndpointConfiguration/ServerEndpointConfiguration getNegotiatedSubprotocol and getNegotiatedExtensions

Propose: Use null for no value / no values rather than empty lists or strings.

Also need to define the default algorithms for the server choosing the subprotocols and extensions.

Propose: for subprotocols, the default DefaultServerEndpointConfiguration will find the 'best match' by returning the first subprotocol in the client list that it has in its own list.

Propose: for extensions, the default DefaultServerEndpointConfiguration will find the 'best matches' by running through the clients preferred list in the order that it came, selecting, in that order, the extensions that it supports in its own server list.

For the Origin check, will Propose the the default handshake will verify the Origin header, if present. See http://tools.ietf.org/html/rfc6455#section-4.2 , paragraph 4.

See Section 4.1 in the EDR. This can be enforced at development time provided we are using using @target on the annotation definitions.

In particular, Session and FrameBuilder, configurations.

RemoteEndpoint/Peer/WebSocket

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.

Currently the API classes and specification do not allow for a very clean separation between

client-only functions (initiating a connection from an endpoint)
server-only functions (publishing an endpoint to accept incoming connections)
common functions: bi-directional messaging over an established connection.

We will need the separation so the specification can clearly define the websocket requirements on client and server platforms, and cleanly produce two API bundles - client API and server API.

Currently I am thinking the the client API does not support publishing endpoints and the server API does not support initiating a connection to endpoints. Also that the server API has to be embedded in a Java EE web container. But there may be demand for a 'standalone' server API in which case we may need to look at how to separate the server requirements appropriately. i.e. standalone is not required to inject the HttpSession.

Suggestions to use

javax.websocket.* instead of javax.websocket.net.*, and also put the annotations in the same package as the main API classes (this is consistent with other EE specs such as servlet and JAX-RS).

Will need to think about this in terms of the client/server split.

2 endpoints mapped to /hello/you and /hello/

{foo}

both match the incoming /hello/you request URI.

Should both endpoints be called ? If not, then should this be a deployment error or should the spec how to determine a winning match (like the servlet spec) ?

Similarly, should multiple message handlers handling the same message type on a session all get the onMessage callback ?

The motivation behind this request is to make a simple programming model consistent with the JAX-RS spec which does not allow programmatic endpoints, just POJO+annotation endpoints. Since this POJO+annotation style has become a central feature of the Java EE programming model, perhaps this spec should only use it ?

This would mean removing Endpoint and the MessageHandler classes. Session, RemoteEndpoint and probably the configuration and container classes would have to remain.

I think there is benefit in standardizing the API-versions of websocket endpoints, even if this does offer two modes in the programming model. The benefit is to standardize on the multiple API-versions of websocket-endpoint out there already, and to cater to developers who do not care for annotations (there are plenty).

Currently the web container allows HttpSessions to be serialized and moved between nodes in a distributed server. The purpose it to dynamically balance the load on a distributed server.

So what does this mean for WebSockets in the distributed environment ?

I need to research this, but it seems unlikely that, without cooperation from the client, such distributed deployments close the TCP connection and reconnect it from a different server location. Which would mean that websocket sessions are tied to the node in the cluster. Which has implications on web applications containing web sockets and limits the ability of the server to move an http session around.

The websocket spec will need to define what is allowable for web socket implementations in the distributed Java EE setting. Currently, it looks like web application sessions can only be moved around if there is some cooperating websocket proxy that is fronting the actual TCP connection.

Will research this.

For now the API has a ContainerProvider class that can use the service loader mechanism to load
different implementations of the Client and Server containers. This will be ok for the Java SE client
API, but probably not for Java EE.

We will explore other mechanisms in the Java EE case. Perhaps making the ServerContainer a CDI managed bean that can
be injected into developer code, perhaps into a ServletContext initializer, for example. Or an annotation that the web
container must scan for that indicates that a given class implementing one of the Container interfaces must be loaded at
startup.

The situation is that an endpoint has two onMessage handlers.

For example: One handles Strings, the other handles Apples. There is an AppleEncoder on the endpoint.

Which method gets called ?

Do these methods block until the client has connected/the endpoint is published ?
Or do they work asynchronously.

as summary.

• For the Client API, the only usage shown is using extends Endpoint and session.getRemote().sendString(...). I was expecting something like:

@Inject WebSocket("/uri") webSocket;

or may be

@Inject WebSocketClient("/uri") wsClient;

Then WebSocketClient can provide Session and other required properties.

We want these two things to be true:

1)if the web socket is a protected resource in the web application, that is to say, required an authorized user to access it, and the user explicitly invalidates the HttpSession, the websocket implementation must close the web socket connection immediately

2. if the user of the web application is actively using the web sockets within the web application, but does not access any of the web resources, the web socket implementation must keep the HttpSession from timing out (TBD This a request to the servlet specification).

This is because authentication state is carried in the Http Session.

But what about the unauthenticated case ? Does an explicit invalidate need to close the web sockets ? Does a timeout matter ?

Section 4.3.3

• Why does the entity have to come in the first parameter? Can't we just say the first (and only) parameter that is not of type Session and isn't annotated with @WebSocketPathParam annotation?
• Why can't the entity param be of any type? Otherwise decoders are never utilized.

Also, @WebSocketMessage javadoc.

Clearly we need at least one Endpoint instance per VM. Should the spec simplify this to say 'exactly one' ? Then the programmer can rely on being able to save state in the endpoint instance in that VM.

Suggested by Martin: It seems that a single endpoint implementation can not be used both on the client and the server side (i.e. I can't think of a use-case where the implementation of both would be the same), also it does not make sense to share the same configuration for multiple endpoints (since that would mean they are all published at the same URI). So why not merging Endpoint and EndpointConfiguration? With a client and server API, we could have ServerEndpoint and ClientEndpoint classes (and delete all *EndpointConfiguration classes - move their methods directly to the Endpoint classes). I think it would simplify it for the users.

Not withstanding the current claim that Section 4B of the JSPA 2 allows an "evaluation license to members of the EC", the wording of Section 4B does not explicitly name the Executive Committee:

B. Grants to Other Expert Group Members. You hereby grant to Member represented on any
Expert Group on which You are also represented under Your applicable patents, copyrights and trade secret
rights which You currently have or may acquire in the future a perpetual, non-exclusive, worldwide, royalty free,
fully paid-up, irrevocable license to use Your Contributions for research and development purposes
related to the activities of such Expert Group. Similarly, Oracle makes the same grant to You with respect to its
Contributions concerning Expert Groups on which You are represented. These grants, from You to other
Members and from Oracle to You, shall not include distribution to third parties of early access implementations
of the Spec under development by Your Expert Group until the draft Spec has been released for Public
Review.

This needs to be spelled out explicitly.

Further, in the interest of transparency, JCP members should be able to provide input on the validity of RIs and TCKs without the burdon of having to become licensees of the technology.

What we want is to be able to prevent httpsessions timing out when web socket connections with that user are active.

One solution is to set the cookie to never expire on the http opening handshake response, and to use httpsession.setMaxInactiveInterval() to a negative value.

http://docs.oracle.com/javaee/5/api/javax/servlet/http/HttpSession.html#setMaxInactiveInterval%28int%29

We are exploring what other (better) ways we can achieve this.

API:

• perhaps Endpoint could have a method returning a set of currently open sessions or for broadcasting messages to all open sessions for a given endpoint?
• Decoders/Encoders - seems there are too many variants of decoders/encoders (binary stream, text stream, binary, text) - can't we simply go with streaming and provide default implicit decoders for Stream<>String and Stream<>byte[] and whatever other types we want to support?
• too many MessageHandler classes. Why can't we simply have MessageHandler, PartialMessageHandler and PongHandler and decide based on the type argument which message handler should be called for a given message?
• for async operations, no way to specify timeouts?
• why is RemoteEndpoint capable of sending only one type of object? Why can't it simply have a single send(M message) method for sending objects of any kind instead of having sendString(), sendObject(), sendBytes() and getSendStream()?
• There is no notion of path params in programmatic API, DefaultServerConfiguration.matchUri() only supports exact match, but annotations support path template matching? That does not seem right.
• should ServerContainer.publishServer() be renamed to publishEndpoint()? Since that's what it seems to do.
• Session should have methods for retrieving path parameters and property bag for storing session-related data
• nitpick - in the Endpoint, session param should come first in onError to make it more consistent with onOpen and onClose

Make the parameter and return type List, not List

May need ability to look up installed extension instances by String name.

WebSockets supported on Web Containers can do their own bootstrapping and selection of implementation. So does the developer API really need to define this entry point ?

On the other hand, since people may want to define standalone web socket servers, outside the context of the web container, won't they need some standard way to get the ServerContainer and deploy their endpoints ? Or is it ok for that part of their deployment of web sockets on standalone websocket servers to be proprietary ?

Because it is visual noise.

If we do, we'd need to define how to map an endpoint to the context root '/'.