jakartaee / websocket Goto Github PK
View Code? Open in Web Editor NEWJakarta WebSocket
Home Page: https://projects.eclipse.org/projects/ee4j.websocket
License: Other
Jakarta WebSocket
Home Page: https://projects.eclipse.org/projects/ee4j.websocket
License: Other
Make the parameter and return type List, not List
May need ability to look up installed extension instances by String name.
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.
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.)
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 ?
Use an annotation for automatic deployment of subclasses of Endpoint (possibly instead of publishEndpoint)
Use web socket annotations on the client side.
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.
as summary.
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.
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.
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.
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.
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 ?
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/
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.
Perhaps public Map<String, String> getURISegments() on Session.
Section 4.3:
In particular:
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 ?
As summary. Some people think we should not have programmatic APIs for creating endpoints.
@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 ?
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.
Do these methods block until the client has connected/the endpoint is published ?
Or do they work asynchronously.
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()
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'.
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 ?
Because it is visual noise.
If we do, we'd need to define how to map an endpoint to the context root '/'.
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
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 ?
Will research this.
Otherwise the implementation can't use it !
@Inject WebSocket("/uri") webSocket;
or may be
@Inject WebSocketClient("/uri") wsClient;
Then WebSocketClient can provide Session and other required properties.
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.
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).
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.
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.
We are exploring what other (better) ways we can achieve this.
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.
Its not necessary, and it would also make this spec consistent with JAX-RS.
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).
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.
Section 4.3.3
Also, @WebSocketMessage javadoc.
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.
See, for example, the Guava project
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 ?
API:
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.
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).
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.
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.
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."
See Section 4.1 in the EDR. This can be enforced at development time provided we are using using @target on the annotation definitions.
Then the user knows about the failure cases.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.