[WEBSOCKET_SPEC-2] TCK/RI license terms prevent EC evaluation Created: 02/Mar/12  Updated: 30/Oct/12  Resolved: 30/Oct/12

Status: Closed
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Major
Reporter: starksm64 Assignee: dannycoward
Resolution: Invalid Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

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.



 Comments   
Comment by dannycoward [ 30/Oct/12 ]

This is the venue for tracking technical issues with the JSR 356 specification.

I am closing this issue because it isn't a technical; this is not the right venue for a discussion about the legal aspects of Oracle's TCK License.

Scott, I am going to ask you to raise this at in JCP Executive Committee directly through your representative, Mark Little.





[WEBSOCKET_SPEC-1] TCK license conflicts with JCP 2.8 section 1.4 Created: 02/Mar/12  Updated: 30/Oct/12  Resolved: 30/Oct/12

Status: Closed
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Major
Reporter: starksm64 Assignee: dannycoward
Resolution: Invalid Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Attachments: PDF File SATCK JSR 356 JavaAPI for Web Sockets 1.0 redline 2 29 12.pdf    

 Description   

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."



 Comments   
Comment by starksm64 [ 02/Mar/12 ]

Items that continue be in conflict with the requirement include the following from section 2.1(b) of the attached TCK redline document:

(iv) develop other test suites intended to validate compatibility with the Java Specification(s) to which the TCK(s) licensed hereunder corresponds; or

(vi) use the TCK to make claims of comparative compatibility (for example, a claim either that a Product is “90% compatible” or that the Product is “more compatible” than another implementation of the same Java Specification).

Comment by dannycoward [ 30/Oct/12 ]

This is the venue for tracking technical issues with the JSR 356 specification.

I am closing this issue because it isn't a technical; this is not the right venue for a discussion about the legal aspects of Oracle's TCK License.

Scott, I am going to ask you to raise this at in JCP Executive Committee directly through your representative, Mark Little.





[WEBSOCKET_SPEC-172] Define what Exception should be thrown if Session#addMessageHandler, Session#close, Session#getRemote called on already closed Session instance. Created: 13/Mar/13  Updated: 19/Mar/13  Resolved: 19/Mar/13

Status: Closed
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: stepan.kopriva Assignee: dannycoward
Resolution: Duplicate Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: final

 Description   

Session#close wouldn't throw exception since it needs to adhere to Closeable#close() contract.

I would think it would be IllegalStateException in other cases.



 Comments   
Comment by stepan.kopriva [ 14/Mar/13 ]

OK I agree, but I think it needs to be designed which Session methods should throw the exception and when.
For example if Session#addMessageHandler throws exception, should Session#removeMessageHandler throw one etc.

Comment by dannycoward [ 18/Mar/13 ]

There is a class level comment:-

  • <p>Once the session is closed, it is no longer valid for use by applications. Calling any of
  • its methods once the session has been closed will result in an {@link java.lang.IllegalStateException}

    being thrown.

  • Developers should retrieve any information from the session during the
  • {@link Endpoint#onClose }

    method.

is that specific enough ?

BTW: I think once the session is closed calling close again is weird. I think IllegalState is good for that particular case too.

Comment by jitu [ 18/Mar/13 ]

Session#close need to follow Closeable#close semantics since Session is implementing Closeable. Closeable#close allows closing an object multiple times without throwing an exception.

Comment by dannycoward [ 19/Mar/13 ]

closing this since 174 has more detail.





[WEBSOCKET_SPEC-48] Clarify precedence of MessageHandler calling in the case where there are multiple handlers Created: 22/Oct/12  Updated: 09/Nov/12  Due: 09/Nov/12  Resolved: 09/Nov/12

Status: Closed
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Duplicate Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

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).



 Comments   
Comment by dannycoward [ 09/Nov/12 ]

Duplicate of 39





[WEBSOCKET_SPEC-40] Defer ability to subclass Endpoint to next version. Just rely on POJOs Created: 17/Oct/12  Updated: 29/Oct/12  Resolved: 29/Oct/12

Status: Closed
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: Unassigned
Resolution: Duplicate Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

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



 Comments   
Comment by dannycoward [ 29/Oct/12 ]

Closing because this is a duplicate of issue 14, so we will deal with the feedback there.





[WEBSOCKET_SPEC-31] Specify relationship between Web Socket Session and HttpSession Created: 17/Oct/12  Updated: 30/Nov/12  Due: 09/Nov/12  Resolved: 30/Nov/12

Status: Closed
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Duplicate Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

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.



 Comments   
Comment by Martin Matula [ 09/Nov/12 ]

This is a duplicate of WEBSOCKET_SPEC-5

Comment by dannycoward [ 30/Nov/12 ]

duplicate of issue #5





[WEBSOCKET_SPEC-21] How many Endpoint instances ? Created: 12/Oct/12  Updated: 03/Nov/12  Due: 09/Nov/12  Resolved: 03/Nov/12

Status: Closed
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Duplicate Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

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.



 Comments   
Comment by dannycoward [ 03/Nov/12 ]

More recent feedback is guiding us towards having one instance per connection.

Comment by dannycoward [ 03/Nov/12 ]

of 37





[WEBSOCKET_SPEC-19] Encoder/Decoder mechanism: Can we reuse the JAX-RS scheme ? Created: 12/Oct/12  Updated: 09/Nov/12  Due: 09/Nov/12  Resolved: 09/Nov/12

Status: Closed
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

Will research this.



 Comments   
Comment by dannycoward [ 09/Nov/12 ]

Duplicate of 25





[WEBSOCKET_SPEC-125] ServerApplicationConfiguration should be renamed Created: 28/Jan/13  Updated: 08/Feb/13  Resolved: 08/Feb/13

Status: Closed
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Minor
Reporter: stepan.kopriva Assignee: Unassigned
Resolution: Duplicate Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

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.



 Comments   
Comment by dannycoward [ 01/Feb/13 ]

any suggestions ?

how about ServerDeployentFilter ?

Comment by dannycoward [ 08/Feb/13 ]

This hasn't been resolved, but I've added it to http://java.net/jira/browse/WEBSOCKET_SPEC-9 which deals with a fe renaming issues. We need to consider all the potential renames at once, so we have a consistent look.

So I'm closing it as a duplicated and tracking it in 9 instead.





[WEBSOCKET_SPEC-226] Session.addMessageHandler(MessageHandler) cannot work with lambda expressions. Created: 12/May/14  Updated: 06/Aug/14  Resolved: 06/Aug/14

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: 1.0
Fix Version/s: 1.1

Type: Bug Priority: Blocker
Reporter: Pavel Bucek Assignee: Pavel Bucek
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
is related to TYRUS-302 Java 8 Lambda Resolved

 Description   

+ other implied generics issues.

The method "addMessageHandler" forces implementation to get generic type of the message handler instance. Problem is that this information does not need to be always available - for example for lambda expressions (MessageHandler is interface with only one method, thus can be replaced with lambda). There are other cases where this method does not work and any generics expert will confirm that this is not correctly defined; basically whenever there is no info in the class file for supplied argument, it won't work.

Marking this issue as "Blocker" since it has multiple consequences - lambdas cannot be used and using current version of the API from Nashorn (and other JVM languages) is difficult of not impossible for some cases. Also, addMessageHandler is vial method for programmatic part of the API - it cannot be workarounded.

proposed solution:

add two methods to Session

public <T> void addMessageHandler(Class<T> clazz, MessageHandler.Partial<T> handler);
public <T> void addMessageHandler(Class<T> clazz, MessageHandler.Whole<T> handler);

discussion:

proposed solution provides additional information about the generic type, usable in all cases. Drawback is that types like `List<String>` cannot be represented, but there is currently no standard way in Java how to represent these types. Suggested workaround would be to represent this type by non-generic variant. In our sample we could introduce class/interface `StringList` which would extend `List<String>`.



 Comments   
Comment by Pavel Bucek [ 12/May/14 ]

original issue reported against RI - Tyrus

Comment by stuartdouglas [ 21/May/14 ]

This can be worked around to some extent as mentioned here: https://issues.jboss.org/browse/WFLY-3254

Basically you need to define an interface that extends the message handler interface, and then cast the lambda to this type:

interface StringWholeMessageHandler extends MessageHandler.Whole<String>{}

session.addMessageHandler((StringWholeMessageHandler) message -> {

Comment by Pavel Bucek [ 06/Aug/14 ]

proposed solution was accepted and is part of 1.1 MR.





[WEBSOCKET_SPEC-177] Invalid JavaDoc definition of Session.getAsyncRemote() & Session.getBasicRemote(). Created: 01/Apr/13  Updated: 02/Apr/13  Resolved: 02/Apr/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: 1.0
Fix Version/s: None

Type: Bug Priority: Critical
Reporter: Mohamed Taman Assignee: Unassigned
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified
Environment:

Proposed final draft v1.0


Tags: final, fishcat, javadoc

 Description   

The JavaDoc states the following:

RemoteEndpoint.Async getAsyncRemote()
Return a reference a RemoteEndpoint object representing the peer of this conversation that is able to send messages synchronously to the peer.

synchronously should be asynchronously

And

RemoteEndpoint.Basic getBasicRemote()
Return a reference a RemoteEndpoint object representing the peer of this conversation that is able to send messages asynchronously to the peer.

asynchronously should be synchronously



 Comments   
Comment by Mohamed Taman [ 01/Apr/13 ]

They are in Session interface.

Comment by dannycoward [ 02/Apr/13 ]

Thanks, this has now been fixed !





[WEBSOCKET_SPEC-89] Extension unification Created: 04/Jan/13  Updated: 09/Jan/13  Resolved: 09/Jan/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Critical
Reporter: Pavel Bucek Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

ClientEndpointConfiguration.getExtensions and Session.getNegotiatedExcensions still use List<String> instead of List<Extension>



 Comments   
Comment by dannycoward [ 09/Jan/13 ]

fixed for v012





[WEBSOCKET_SPEC-82] @WebSocketEndpoint's configuration attribute Created: 03/Jan/13  Updated: 16/Feb/13  Due: 08/Feb/13  Resolved: 16/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Critical
Reporter: jitu Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v013

 Description   

At present (PR draft), @WebSocketEndpoint has a configuration attribute that is a required attribute. This means all the applications (even if they don't want to configure anything) need to pass a subclass of DefaultServerConfiguration. IMO, that's not usuable at all.

DefaultServerConfiguration also has methods to set encoder, decoders and that would conflict with @WebSocketEndpoint's encoders/decoders attributes. That means spec need to define how an impl would construct effective encoders and decoders list.
Moreover, the signature should be something like the following :
public Class<? extends ServerEndpointConfiguration> configuration() default DefaultServerConfiguration.class;

Then, the spec need to define how the configuration object is instantiated and whether it is used per instance or not etc.



 Comments   
Comment by Pavel Bucek [ 04/Jan/13 ]

additionally (I can create a separate issue if needed), Default(Server|Client)Configuration should not be part of API (or I don't see any reason for it). It is just implementation detail => it belongs to implementation.

Comment by dannycoward [ 16/Feb/13 ]



The issues are all now resolved in v013 with the cleaned up config APIs.





[WEBSOCKET_SPEC-126] ServerEndpointConfiguration.matchesURI Created: 28/Jan/13  Updated: 16/Feb/13  Resolved: 16/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Pavel Bucek Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v013

 Description   

There is currently no way how to report matched path parameters to runtime from matchesURI method.

Additionally, matchesURI documentation doesn't seem to cover context-path; at least I can't find any information about what part of URI/URL should be used for matchesURI call.



 Comments   
Comment by dannycoward [ 16/Feb/13 ]

The new API allows for the path parameters in the match method.

The spec has a section 6.4 that deals with the relative roots.

So I think I can close this one.





[WEBSOCKET_SPEC-122] Behaviour of onMessage(some mutable object) not defined Created: 24/Jan/13  Updated: 02/Feb/13  Resolved: 02/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: markt_asf Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

The specification does not define the scope of validity for objects passed to message handling methods. Is the object only valid for the duration of the method or for all time?



 Comments   
Comment by dannycoward [ 31/Jan/13 ]

Hey Mark : Which objects in particular ?

Session - I think is well-scoped: the object is valid as long as the connection is open
Config - valid as long as the endpoint instance is around

Perhaps you mean some of the various (mutable) message objects ?

Do you want the container to be able to reuse a ByteBuffer once the onMessage has been completed ? And so require the developer to consume the message within the onMessage(), and discourage them referencing the ByteBuffer outside the scope of that call ?

Comment by markt_asf [ 31/Jan/13 ]

I do mean the various message objects.

I have no strong preference for how the validity is scoped.

If the scope is limited to within the onMessage() call then we'll almost certainly have to add some form of protection to stop developers using the objects outside of that scope (although that is more an implementation concern than a spec one). Personally, I have a slight preference for this but would be happy with a "here is the object, do what you like with it" approach as well.

I am far more concerned that the scope of validity of these objects is clearly defined than what the scope actually is.

Comment by dannycoward [ 01/Feb/13 ]

OK I understand.

I think it'd be more convenient for developers to be able to use these objects however they want, put them in hashtables, variables etc. So I think I'd vote for it that way.

Let's see if anyone else has opinions on the eg.

Comment by dannycoward [ 02/Feb/13 ]

OK I think you and Scott have persuaded me: Reader/InputStream/ByteBuffers should not be references outside the scope of the onMessage callbacks.





[WEBSOCKET_SPEC-121] RemoteEndpoint#[sendPing()|sendPong()] should throw IOException Created: 22/Jan/13  Updated: 26/Jan/13  Due: 01/Feb/13  Resolved: 26/Jan/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: markt_asf Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

Like the other send methods, these methods need to be able to indicate to the caller that the send failed.



 Comments   
Comment by dannycoward [ 22/Jan/13 ]

Yes I agree.

Comment by dannycoward [ 26/Jan/13 ]

fixed as suggested.





[WEBSOCKET_SPEC-120] Allow multiple ClientContainers per VM Created: 18/Jan/13  Updated: 26/Jan/13  Due: 25/Jan/13  Resolved: 26/Jan/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

(from Joe)

The ContainerProvider.getClientContainer() method provides a singleton WebSocketContainer implementation.

Issues:

1. This means you can only have one configuration of WebSocketContainer per application. It's likely that an application may connect to many servers and would want different configuration paramaters for each of these.

2. Multiple parts of the application can be running on different threads - they would have to coordinate access to the singleton instance.

3. It is likely that third party libraries will build clients based on top of the WebSocket protocol and the singleton WebSocketContainer implementation. These libraries may have conflicting requirements of optimal settings on the WebSocketContainer, and even override your own applications settings without it being obvious.

Proposal:

ContainerProvider.getClientContainer() should always return a new instance rather than a shared singleton.

This allows isolated instances to be used my multiple parts on the applications, in different threads and even by third party libraries, without the risk of conflict. If applications really do wish to use a singleton, they can share the instance themselves.

Should probably rename it to newClientContainer().

-Joe



 Comments   
Comment by dannycoward [ 26/Jan/13 ]

This is resolved in v012.





[WEBSOCKET_SPEC-119] WebSocketContainer can't be a singleton Created: 17/Jan/13  Updated: 26/Jan/13  Due: 25/Jan/13  Resolved: 26/Jan/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: markt_asf Assignee: Unassigned
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

The Javadoc for ContainerProvider states that the returned WebSocketContainer is a singleton. That isn't going to work in container environments - consider getOpenSession(). There needs to be an instance per web application which boils down - essentially - to an instance per class loader.

The same will apply to the server container if/whan it is re-added.



 Comments   
Comment by dannycoward [ 26/Jan/13 ]

This is updated in v012.





[WEBSOCKET_SPEC-117] Provide way to inform developers when connections timeout or close (without close frames being sent) Created: 17/Jan/13  Updated: 06/Feb/13  Due: 05/Feb/13  Resolved: 06/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

I can't see how the endpoint can be notified that its connection has timed out (or disconnected w/o a close.)

Should there be a CloseCodes.TIMEOUT (or READ/WRITE_TIMEOUT), and CloseCodes.CONNECTION_DISCONNECT?

Or should there be some exceptions for @WebSocketError like WebSocketTimeoutException (or WebSocketRead/WriteTimeout) and WebSocketDisconnectException.



 Comments   
Comment by dannycoward [ 06/Feb/13 ]

We determined in the eg that the onClose method should be called whether the close is as a result of a remotely sent close frame, or locally due to some event like a timeout.

To distinguish between the two, we're going to use the reserved 1006 code (which the websocket protocol disallows from use in a close frame) for locally initiated closes, with suitable reason phrase.





[WEBSOCKET_SPEC-116] WebSocketContainer.connectToServer ease of use / API change Created: 17/Jan/13  Updated: 01/Mar/13  Resolved: 01/Mar/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
is related to WEBSOCKET_SPEC-69 Publish same programmatic endpoint t... Resolved
Tags: v014

 Description   

(from Scott)

The new connectToServer is difficult to use.

Instead of a Class parameter, it should be an object. The container shouldn't need to instantiate the object, and the Class model makes it difficult to connect between the client application and the client endpoint. (Because any shared state/object needs to be passed through a custom ClientEndpointConfiguration.)

The API should be simplified to:

WebSocketContainer {
Session connectToServer(Object endpoint, URI path);

Session connectToServer(Object endpoint, URI path, ClientEndpointConfiguration cec);
}

If the "endpoint" object is already of type Endpoint, it's used directly. Otherwise, a skeleton/proxy is created, i.e. annotation stuff.

There's no need for separate methods for Endpoint vs annotation.



 Comments   
Comment by dannycoward [ 01/Mar/13 ]

awaiting last feedback on whether to add these methods

Comment by dannycoward [ 01/Mar/13 ]

This has been added in v014, with the disclaimers that dependency injection may not work.





[WEBSOCKET_SPEC-115] Pls revert to EndpointFactory instead of EndpointConfig scheme Created: 17/Jan/13  Updated: 28/Feb/13  Due: 08/Feb/13  Resolved: 28/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v014

 Description   

(from Joe...)

This could work, but I see a few issues the EndpointConfiguration approach has, that are avoided in the EndpointFactory approach:

1. It involves an ugly cast. Not the end of the world, but still...

public class MyEndpoint extends Endpoint {
public void onOpen(Session session, EndpointConfiguration config)

{ MyEndpointConfig myConfig = (MyEndpointConfig)config; // cast this.db = myConfig.getMyDatabaseConnection(); }

}

2. Because the dependencies aren't set in the constructor, the fields can't be final. Not a show stopper, but marking dependencies final contributes to making safer and easier to understand code.

3. It's hard to manage scope of multiple dependencies. Easier to explain with an example.

If we had the EndpointFactory, we could do something like this:

class MyEndpoint {
MyEndpoint(EmployeeFinder dep1, Payroll dep2)

{ ... }

}

class MyEndpointFactory implements EndpointFactory {
Object createEndpoint()

{ DatabaseConnection conn = new DatabaseConnection(this.someSharedState); // scoped only for this single Endpoint instance. EmployeeFinder employeeFinder = new EmployeeFinder(this.someSharedState, conn); Payroll payroll = new Payroll(this.differentSharedState, conn); return new MyEndpoint(employeeFinder, payroll); }

}

Trying to do that with the EndpointConfiguration:

class MyEndpoint {
public void onOpen(Session session, EndpointConfiguration config)

{ MyEndpointConfig myConfig = (MyEndpointConfig)config; // cast DatabaseConnection conn = myConfig.newDatabaseConnection(); this.employeeFinder = myConfig.newEmployeeFinder(conn); this.payroll = myConfig.newPayroll(conn); }

}

My issue with this is that details of how to assemble the external dependencies are now present inside the Endpoint implementation. Ideally the Endpoint should only care about the direct dependencies it needs, not the dependencies of dependencies. The underlying problem is that it cannot simply call config.getSomething(), config.getAnother() because the config implementation does not have a way of providing a shared dependency to both of those, but only for a single Endpoint instance.

4. It creates a tight coupling between an Endpoint implementation and an EndpointConfiguration. This makes it hard to reuse an Endpoint in different configurations. With the EndpointFactory approach the dependency is the other way around, allowing an Endpoint to be created by multiple factories that can assemble different dependency graphs.

Overall, I much prefer the EndpointFactory approach you proposed - it's clean, inutuitive, and keeps the details of the dependency implementations external.

How about we add the EndpointFactory interface, as you proposed. User gets to choose ONE of:

  • A default implementation simply instantiates the class using a no-args constructor.
  • An EJB or CDI implementation that uses existing mechanisms to instantiate the Endpoint.
  • A custom Endpoint specific implementation (e.g. MyEndpointFactory above).
  • An integration with the user's favorite third party DI framework of choosing.

Basically, if you specify your own EndpointFactory, you're using that instead of the EJB/CDI factory.



 Comments   
Comment by dannycoward [ 28/Feb/13 ]

We are prototyping

Configurator->public Object getEndpointInstance() throws InstantiationException;

which the eg seemed to like.

Comment by dannycoward [ 28/Feb/13 ]

v014 allows the developer to control the instance creation of endpoints using the

ServerEndpointConfig.Configurator.getEndpointInstance(Class<T> endpointClass) call.





[WEBSOCKET_SPEC-114] Programmatic deployment of server endpoints Created: 17/Jan/13  Updated: 28/Feb/13  Resolved: 28/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
is related to WEBSOCKET_SPEC-79 Deployment on the server by instance Resolved
is related to WEBSOCKET_SPEC-69 Publish same programmatic endpoint t... Resolved
Tags: v014

 Description   

Please add it back in ! (from Mark)



 Comments   
Comment by dannycoward [ 28/Feb/13 ]

We've added a programmatic API, callable at initialization time in for v014





[WEBSOCKET_SPEC-241] Relax restriction to programmatically register endpoints during deploy phase only Created: 21/Dec/15  Updated: 21/Dec/15  Resolved: 21/Dec/15

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: balusc Assignee: Pavel Bucek
Resolution: Duplicate Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Duplicate
duplicates WEBSOCKET_SPEC-211 Remove restriction on when a server e... Open

 Description   

WS spec chapter 6.4 says the following:

Developers may deploy server endpoints programmatically by using one of the addEndpoint methods of the ServerContainer interface. These methods are only operational during the application deployment phase of an application. Specifically, as soon as any of the server endpoints within the application have accepted an opening handshake request, the apis may not longer be used. This restriction may be relaxed in a future version.

In practice, it turns out that only Tyrus throws an IllegalStateException when developers try to add endpoint after deploy phase. Tomcat and Undertow allow this and it works fine.

Given that this restriction could be relaxed in a future version, hereby I propose to do with next release. This would immediately solve the problems outlined in https://java.net/jira/browse/WEBSOCKET_SPEC-240 and https://java.net/jira/browse/TYRUS-420.






[WEBSOCKET_SPEC-227] Asynchronous connectToServer Created: 20/May/14  Updated: 20/May/14  Resolved: 20/May/14

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: 2.0
Fix Version/s: None

Type: New Feature Priority: Major
Reporter: mwessendorf Assignee: Pavel Bucek
Resolution: Duplicate Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Duplicate
duplicates WEBSOCKET_SPEC-214 Introduce non-blocking WebSocketConta... Open

 Description   

Please add a way to allow developers to connect to the server in an asynchronous way

https://blogs.oracle.com/PavelBucek/entry/asynchronous_connecttoserver



 Comments   
Comment by Pavel Bucek [ 20/May/14 ]

Duplicate of https://java.net/jira/browse/WEBSOCKET_SPEC-214





[WEBSOCKET_SPEC-174] Add more detail to javax.websocket.Session JavaDoc about which methods do not throw IllegalStateException Created: 19/Mar/13  Updated: 07/Dec/13  Resolved: 21/Mar/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: 1.0
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Nick Williams Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: 15 minutes
Time Spent: Not Specified
Original Estimate: 15 minutes

Tags: final

 Description   

Current JavaDoc says this:

Once the session is closed, it is no longer valid for use by applications. Calling any of its methods once the session has been closed will result in an IllegalStateException being thrown. Developers should retrieve any information from the session during the Endpoint.onClose(javax.websocket.Session, javax.websocket.CloseReason) method.

I believe this needs more clarification. I submit the following:

  • close() and close(CloseReason), in accordance with the java.io.Closeable contract, must NOT throw an exception if the Session is already closed, but instead calling these after Session close should be a no-op. Since this is specified already in Closeable, it may or may not be necessary to specify this in Session, but I suggest it doesn't hurt, and makes it 100% unambiguous.
  • isOpen() should NOT throw an exception, since it is used to indicate whether the Session is open (and, thus, whether a subsequent call to some other method is unlikely to throw an IllegalStateException).
  • getId() should NOT throw an exception, since the String it returns cannot be acted upon, and the ID could be useful debugging/tracking/logging/troubleshooting information post-close.


 Comments   
Comment by Nick Williams [ 19/Mar/13 ]

Now that I think about it, even more clarification is needed. Consider this: Whether I call Session#close(...) or the remote endpoint closes the Session, it is not valid to send messages on the remote endpoint in Endpoint#onClose(...). But the JavaDoc implicitly suggests that Endpoint#onClose(...) can call any Session method without throwing an IllegalStateException. I do not believe this is correct. For the most part, Session methods shouldn't throw IllegalStateException until AFTER Endpoint#onClose(...) returns. However, I believe the following methods should throw IllegalStateExceptions if called from Endpoint#onClose(...):

  • addMessageHandler(MessageHandler)
  • removeMessageHandler(MessageHandler)
  • Any set* methods.
  • getAsyncRemote()
  • getBasicRemote()

This can simply be handled by (internally) assuming the session has three states: OPEN, CLOSING and CLOSED. It's OPEN until close(...) is called locally or remotely, then it's CLOSING until Endpoint#onClose(...) returns, then it's CLOSED. The methods mentioned in this comment throw an IllegalStateException if the session state != OPEN, the rest of the methods throw an IllegalStateException if the session state == CLOSED, except for the four exceptions noted above, which never throw IllegalStateException.

Thoughts?

Comment by dannycoward [ 21/Mar/13 ]

I think you're right. I've clarified that during on close developers can access the session information (id, user data etc), but should not try to modify any of the data, nor try to send messages.

I think that covers the cases that could cause issues.

I think CLOSING is a good way to model it internally, although there are even two sorts of closing: one is closing initiated locally, and one is closing after receipt of a close frame from the client.

Comment by Nick Williams [ 15/Apr/13 ]

I think we need slightly more clarification still. See this bug:

https://issues.apache.org/bugzilla/show_bug.cgi?id=54746

I must be able to call certain methods to obtain information from a session (getId, getRequestParameterMap, getRequestURI, getUserPrincipal, getUserProperties, getContainer, getPathParameters, getQueryString) even after a session is closed. This is especially important if onError is called after a session is closed (as is the case with this bug). The data provided by these methods is crucial to log an error and help track down its cause.

I propose that these eight methods be made to NEVER throw an IllegalStateException. No benefit is gained from throwing an IllegalStateException in these methods after the Session is closed, and no danger is created by not throwing an IllegalStateException. These methods are by their very nature idempotent.

Comment by Nick Williams [ 07/Dec/13 ]

I would love to get this further clarified for Java EE 8, as per the comment above.





[WEBSOCKET_SPEC-173] javax.websocket.DecodeException lacking constructors for InputStream, Reader Created: 17/Mar/13  Updated: 02/Apr/13  Resolved: 19/Mar/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: 1.0
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Nick Williams Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: 1 hour
Time Spent: Not Specified
Original Estimate: 1 hour

Tags: final

 Description   

javax.websocket.DecodeException only has constructors for ByteBuffer and String. It does not have constructors for InputStream or Reader, and it does not have constructors that don't take objects needed decoding.

Suggest the following constructors get added:

DecodeException(InputStream, String)
DecodeException(InputStream, String, Throwable)
DecodeException(Reader, String)
DecodeException(Reader, String, Throwable)

OR the following constructors get added:

DecodeException(String)
DecodeException(String, Throwable)

Otherwise, a DecodeException cannot be thrown in implementations of javax.websocket.Decoder.BinaryStream<T> or javax.websocket.Decoder.TextStream<T>.



 Comments   
Comment by dannycoward [ 19/Mar/13 ]

The intention was for the streaming decoders that the developer would stick in some relevant part of the message useful to convey to the error handling code, rather than the whole thing. The javadoc did indicate this, but not very consistently. oops.

So the javadoc is now updated to describe this better.

We won't encourage the exceptions to carry the live input streams or readers in the relevant Decoder.BinaryStream and Decoder.TextStream cases since the exceptions may get carried outside the context in which they make sense. Though of course developers could subclass DecodeException to incldue them if they really want to.

Comment by Nick Williams [ 21/Mar/13 ]

The problem with the change made is that it assumes it is even possible to GET "the (part of) the message that could not be decoded." Consider the following code:

@Override
public ChatMessage decode(InputStream inputStream) throws DecodeException, IOException
{
    try
    {
        return ChatMessageDecoderCodec.MAPPER.readValue(
                inputStream, ChatMessage.class
        );
    }
    catch(JsonParseException | JsonMappingException e)
    {
        throw new DecodeException((ByteBuffer)null, e.getMessage(), e);
    }
}

In this case, MAPPER is an instance of Jackson Mapper's ObjectMapper class. If it fails to decode the input stream, it just fails. There is no way to know where in the decoding process it failed. Thankfully it turns out I can send null as the first argument to the DecodeException constructor, but I would argue this exception really needs at least a DecodeException(String message, Throwable cause) constructor, and maybe also a DecodeException(String message) constructor.

Comment by Nick Williams [ 02/Apr/13 ]

I'd love some feedback on this. I'm not convinced DecodeException doesn't need more constructors.





[WEBSOCKET_SPEC-170] Add examples to spec to clarify URI-template matching precendence Created: 11/Mar/13  Updated: 21/Mar/13  Resolved: 21/Mar/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: final

 Description   

(from Jan)

@ServerEndpoint(value = "/different/

{param1}/{param2}")
public class WS2DifferentPathParamsServer {
@OnMessage
public String param(@PathParam("param1") boolean b1,
@PathParam("param2") char p2, String content) { return String.valueOf(b1) + String.valueOf(p2); }
}

@ServerEndpoint(value = "/{param1}

")
public class WSDirectStringPathParamServer {
@OnMessage
public String param(@PathParam("param1") String p1, String content)

{ return p1; }

}

When I try:
ws://localhost:8080/ws/different/true/0, the second endpoint is matched.



 Comments   
Comment by dannycoward [ 19/Mar/13 ]

This has revealed a number of issues. Here they are with the proposed fixes:-

1) The default container match scheme is not fully defined.

This shows up in cases where an incoming URI may potentially exact match one endpoint and also match another endpoint which uses a URI template. And potentially matches a third endpoint that uses another URI template. Which one gets the match ?

Here's what I propose:-

The container will attempt to match an incoming URI to an endpoint path (URI or level 1 URI-template) as follows:-
The container will recursively try to exact match the longest shared path prefix common to both incoming URI and endpoint path, done by stepping down the paths one segment at a time, using '/' as the separator.
If the shared path prefix is the same as the endpoint path and also the same as the incoming URI, then the paths match (end).
If the shared path prefix is the same as the endpoint path, but shorter than the incoming URI, then the paths do not match (end).
If the shared path prefix is the same as the incoming URI, but shorter than the endpoint path then the paths do not match (end).
Otherwise, there are more segments of both paths to compare, so taking the next segment of both incoming URI and endpoint paths:-
If the next segment of the endpoint path is not a variable, it cannot match the next segment in the incoming URI, otherwise the shared path prefix would have included this path, so in this case, the paths do not match (end).
If the next endpoint directory is a variable, assign the value of the variable in the endpoint path to the value of the segment in the incoming URI, and append the segment to the shared path prefix and call it the new shared path prefix. Now repeat the steps above using the new shared path prefix.

So, here are some examples of that in practice:-

suppose an endpoint has path /a/b/
the only incoming URI that matches this is /a/b/

suppose an endpoint is mapped to /a/

{var}
incoming URIs that do match: /a/b (with var=b), /a/apple (with var=apple)
URIs that do NOT match: /a, /a/b/c (because empty string and strings with reserved characters "/" are not valid URI-template level 1 expansions.)

suppose we have three endpoints and their paths:
endpoint A: /a/{var}

/c
endpoint B: /a/b/c
endpoint C: /a/

{var1}/{var2}
incoming URI: a/b/c matches B, not A or C, because an exact match is preferred.
incoming URI: a/d/c matches A with variable var=d, because like goldlocks, its just right
incoming URI: a/x/y/ matches C, with var1=x, var2=y

endpoint A: /{var1}

/d
endpoint B: /b/

{var2}

incoming URI: /b/d matches B with var2=d, not A with var1=b because the matching process works from left to right.

2) The ServerEndpointConfig.Configurator.matchesURI(URI incoming, String endpointPath) method cannot be supported without further specification changes.

There are two problems: one is, does a developer provided match overrule the default match algorithm ? And, second, if several *Configurator.matchesURI()'s report a match, which one wins ?

As I wrote last week, we could resolve this by saying configurator matchesURI wins over the default algorithm, and also imposing an order on the endpoints, though this latter part would be a bit tricky to specify properly. I suggested ordering what are currently Sets in the returns from the ServerApplicationConfig methods, define the precedence in relation to programmatically deployed endpoints. And use the order of all that to give an order of precendence of the configurators matchesURI results. But then we would still have the problem of how to order any annotated endpoints deployed as a result of a scan when there is no ServerApplicationConfig. Maybe we'd need some global priority ordering scheme...

The issue that's hard to get away from is that for a proper URI matching scheme, the scheme really needs to know ALL the endpoint paths in the application in order to determine a best match out of several candidates. Ordering the paths and picking off the first YES on a binary endpoint-level YES/NO match is a special case of that, and while we could define some kind of ordering, it neither feels especially useful nor simple to put into practice for developers.

So I hate to remove API at this point, but I am proposing removing the ServerEndpointConfig.Configurator.matchesURI() call and deferring the ability to override the matching scheme until the next version when we can define a proper application-level scheme for defining URI matching policies instead of trying to make it work at the endpoint level.

Comment by dannycoward [ 21/Mar/13 ]

resolved as proposed in the spec, examples added.





[WEBSOCKET_SPEC-168] websockets api: improve maxMessage description Created: 11/Mar/13  Updated: 19/Mar/13  Resolved: 19/Mar/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: 1.0
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: mikc22 Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: final

 Description   

The current maxMessageSize annotation javadoc doesn't say when we can use this annotation and what is the behaviour on specified endpoints. E.g. can I supply maxMessageSize for stream as well ?



 Comments   
Comment by dannycoward [ 11/Mar/13 ]

this should correspond to the semantics of the session.getMaxTextMessageBufferSize().

Comment by dannycoward [ 19/Mar/13 ]

I read back the original request. For this version, the attribute only applies when annotating methods that take the whole message, not for partial message processing handlers or those using Readers or InputStreams. The javadoc has been appropriately updated.





[WEBSOCKET_SPEC-167] Encoder/Decoder class hierarchy. Created: 08/Mar/13  Updated: 19/Mar/13  Resolved: 19/Mar/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: 1.0
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Pavel Bucek Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: final

 Description   

Encoder and Decoder share init(EndpointConfig ec) and destroy() methods. These could be in some new interface called "Initiable" (or somewhat better, I'm not very good in naming things) and Encoder/Decoder would extend that.

Encoder.Adapter/Decoder.Adapter could be then minimized to just Coder.Adapter. Current state is that Encoder/Decoder just duplicates some code and it is even legal to have something like

public class MyDecoder extends Encoder.Adapter implements Decoder.Text<AuctionMessage> {
// ...
}

which does not look good.

And if you consider having class, which acts as Encoder and Decoder, then it is not clear which adapter should be used (the fact that it does not really matter is another thing).



 Comments   
Comment by dannycoward [ 19/Mar/13 ]

we agreed just to remove the *.Adapters as developer can quite easily implement their own no-op superclass for the init() and destroy() methods.





[WEBSOCKET_SPEC-166] New method Session#getLocal() Created: 08/Mar/13  Updated: 19/Mar/13  Resolved: 19/Mar/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: markt_asf Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: final

 Description   

Adding the following method to the session would help with error handling as it would provide access to the onError method of the Endpoint:
public Endpoint getLocal()

I'd find this particularly useful when handling DecodeExceptions



 Comments   
Comment by dannycoward [ 11/Mar/13 ]

Hey Mark: Where would you need to call this method from ?

From the developers point of view, all access to the Session occurs within the (local) endpoint the underlying connection is connected to. So, you already know the local endpoint: its this.

I can see that inside the implementation this would be a useful call to have. But, if it is only called by the implementation, why can it not be an implementation specific method on the implementation of Session ?

  • d
Comment by markt_asf [ 12/Mar/13 ]

I use it in a custom message handler to signal a (potentially) non-fatal error to the endpoint. I have no other way to navigate from MessageHandler to Endpoint.

It is a nice to have rather than a must have.

Comment by dannycoward [ 19/Mar/13 ]

OK - thanks. Then I think we will not add this, per our exchange on the expert group.





[WEBSOCKET_SPEC-164] API nits Created: 06/Mar/13  Updated: 06/Mar/13  Resolved: 06/Mar/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: markt_asf Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: proposedfinaldraft

 Description   

In DefaultServerEndpointConfig constructor
Class endpointClass -> Class<?> endpointClass

In ServerEndpointConfig.Builder.create()
Class endpointClass -> Class<?> endpointClass



 Comments   
Comment by dannycoward [ 06/Mar/13 ]

Thanks Mark - I've fixed this (and found one more of the same kind) for PFD.





[WEBSOCKET_SPEC-163] ServerContainer (multiple issues) Created: 06/Mar/13  Updated: 07/Mar/13  Resolved: 07/Mar/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: 1.0
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Pavel Bucek Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: proposedfinaldraft

 Description   
  • ServerContainer should NOT extend WebSocketContainer
  • ServerContainer methods should NOT throw DeploymentException - we already have a mechanism which validates deployed endpoints, but this is being executed during (Filter) initialization phase. Having DeploymentException here will force us to do this twice. Deployment phase (as defined in ServerContainer) seems more like collecting set of classes which will be taken into consideration during deployment, not anything else.


 Comments   
Comment by markt_asf [ 06/Mar/13 ]

Re: ServerContainer should NOT extend WebSocketContainer
Why?
I don't object to this change but I'd like to understand why you want to change it. It seems natural to me.

ServerContainer methods should NOT throw DeploymentException
This I do disagree with. Just because you opt to make a note of the request and deploy later - other implementations are free to make different design decisions. Further, a requested enhancement (not in 1.0) was to be able to deploy at any point in time. When that feature is added (or if containers opt to permit it now) these methods will need to throw a DeploymentException.

Comment by markt_asf [ 06/Mar/13 ]

One additional issue is how to resolve the following:

In a purely programmatic deployment on a Servlet container (no annotations, no SCIs) the implementation will need a reference to the ServletContext in order to configure a Servlet/Filter/Something to handle WebSocket connections.

There is currently no container/implementation neutral way of providing the ServerContainer with its associated ServletContext. I'd prefer to have a neutral way of doing this rather then having to have something container and/or implementation specific.

Comment by Pavel Bucek [ 06/Mar/13 ]

ad 1)

container is not yet created at that point and this class represents it. Additionally I don't see any point of having possibility to call connectToServer methods during application deployment.

ad 2)

I don't agree with "other implementations are free to make different design decision".

ServerContainer javadoc:

/**
 * The ServerContainer is the specialized view of the WebSocketContainer available
 * in server-side deployments. There is one ServerContainer instance per
 * websocket application. The ServerContainer holds the methods to be able to
 * register server endpoints during the initialization phase of the application.
 * For example, for websocket enabled web containers, the registration methods
 * may be called to register server endpoints from a ServletContextListener 
 * during the deployment of the WAR file containing the endpoint. Once the 
 * application deployment phase is complete, and the websocket application has
 * begun accepting incoming connections, the registration methods may no
 * longer be called.
 * 
 * @author dannycoward 
 */

I can see your point and I was considering to go with two checks of deployed classes/configs, but it just does not make much sense to me if I'm considering ServerContainer as it is currently defined..

Comment by jitu [ 06/Mar/13 ]

>"There is currently no container/implementation neutral way
> of providing the ServerContainer with its associated
> ServletContext. I'd prefer to have a neutral way of doing
> this rather then having to have something container and/or > implementation specific."

Pehaps, it is better to pass the context in the API method
ServerContainerProvider.getServerContainer(Object ctxt). Then a developer may pass ServletContext in servlet containers to create websocket server container.

Comment by markt_asf [ 06/Mar/13 ]

ServerContainerProvider.getServerContainer(Object ctxt) works for me.

Comment by dannycoward [ 07/Mar/13 ]

We will retain the ServerContainer as a subtype of WebSocketContainer. Programmatic deployment of server endpoints is a container level function specific to server implementations.

Programmatic deployment will require some of the static validity checking of the endpoint to take place at the time of call of the API.

For now, we may need to rely on container specific support to be able to associate the ServerContainer instance with the ServletContext. We haven't made it a goal (yet!) in this project to have the implementations be totally portable across web containers. I'll add this to the list for .next, when we have more implementations to look at to see where there are container specific hooks.

Mark, we will be interested to see how you implement this bootstrap at application deployment time, and will be happy to compare notes when we have it working properly.

I have filed a separate issue (165) on the bootstrap/portability issue so that we can decide, when we have some more implementation experience ourselves and from others, as to how best to address this issue.





[WEBSOCKET_SPEC-162] CloseCodes#getCloseCode(int) impl can be improved Created: 06/Mar/13  Updated: 06/Mar/13  Resolved: 06/Mar/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: jitu Assignee: dannycoward
Resolution: Won't Fix Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: proposedfinaldraft

 Description   

Remove the switch statement and use a map for better performance. Will send/attach the patch to the issue mail.



 Comments   
Comment by dannycoward [ 06/Mar/13 ]

We may end up optimising this yet, but I'm not convinced hashmap lookups are optimized by the JVM any more efficiently than switch statements.

So we will not change this implementation at this point.





[WEBSOCKET_SPEC-160] Clarify ClodeCodes that are not meant to sent over wire Created: 05/Mar/13  Updated: 06/Mar/13  Resolved: 06/Mar/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: 1.0
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: djiao Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Dependency
blocks TYRUS-121 Some CloseCode not supported. Resolved
Tags: proposedfinaldraft

 Description   

Not all CloseCode are meant to sent over wire. For example, 1006. It is used to indicate to Endpoint that close is initiated locally, not remotely. Does spec want to clarify further on how RI should behavior?

Related RI issue has Jitu's comment: http://java.net/jira/browse/TYRUS-121



 Comments   
Comment by dannycoward [ 06/Mar/13 ]

Which close codes can and can't be sent in a websocket close frame is defined in RFC 6455. I have highlighed the link and that it defines further semantics in the javadoc for CloseReason





[WEBSOCKET_SPEC-182] Programmatic endpoints cannot configure Encoders and Decoders Created: 10/Apr/13  Updated: 15/Apr/13  Resolved: 15/Apr/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: final

 Description   

I think this is an oversight that crept in in one of the many refactorings of the EndpointConfig scheme.

The encoder and decoder lists on EndpointConfig are unmodifiable lists. See DefaultClientEndpointConfig and DefaultServerEndpointConfig.

Therefore, programmatic endpoints cannot add encoders and decoders (for example, in the onOpen() method).



 Comments   
Comment by dannycoward [ 15/Apr/13 ]

This is not a problem. Encoders and Decoders for programmatic endpoint have to be set in the ServerApplicationConfig using the ServerEndpointConfig.Builder, or when using the WebSocketContainer.connectToServer using the ClientEndpointConfig.Builder to create the Endpoint config instance.

However, there is the potential for mismatching the decoders and the message handlers as they are configured t different times for programmatic endpoints. So I will close this one and open one up on the design issue.





[WEBSOCKET_SPEC-180] Maven artifact javax.websocket-api erroneously lists javax.websocket-client-api as dependency Created: 07/Apr/13  Updated: 10/Apr/13  Resolved: 10/Apr/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: 1.0
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Nick Williams Assignee: jitu
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

When I include javax.websocket-api as a dependency in my Maven POM, javax.websocket-client-api is indicated is a transient dependency and is automatically downloaded and added to my project. This is incorrect, because all classes in the javax.websocket-client-api artifact are also in the javax.websocket-api artifact. Either javax.websocket-api should not list javax.websocket-client-api as a dependency, or the javax.websocket-client-api classes should not be included in the javax.websocket-api artifact.

Personally, I would argue that there should be a javax.websocket-client-api artifact and a javax.websocket-server-api artifact that depends on it.



 Comments   
Comment by jitu [ 08/Apr/13 ]

I will mark the javax.websocket-client-api dependency optional in javax.websocket-api. So when you use that in your maven project, it won't pull the client dependency to the classpath.

Comment by jitu [ 10/Apr/13 ]

Made that the javax.websocket-client-api as optional dependency.





[WEBSOCKET_SPEC-187] EndPoint javadoc is incorrect about cardinality Created: 18/Apr/13  Updated: 23/Apr/13  Resolved: 23/Apr/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: 1.0
Fix Version/s: None

Type: Bug Priority: Major
Reporter: gregwilkins Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: final

 Description   

The javadoc for EndPoint says that a single instance is created per connection. However this is just a policy implemented by the default ServerEndpoingConfig.Configurator and it is possible (and I'd say advisable) that shared Endpoint instances can be created.

I suggest that the text be updated to:

When deployed as a server endpoint, that is to say, the endpoint is registered to a URL, the server uses the registered ServerEndpointConfig instance to obtain an Endpoint instance. ServerEndpointConfig instances using the default ServerEndpointConfig.Configurator instance will instantiate a new Endpoint object for each connection, which means the developer is guaranteed that there will be at most one thread in each endpoint instance. However, alternative ServerEndpointConfig implementations may change the cardinality of the Endpoint so that an instance is shared between many connections, in which case the developer should write thread safe Endpoint code and use the passed Session instance for any per connection handling.



 Comments   
Comment by dannycoward [ 23/Apr/13 ]

Yes I see the issue - thanks ! I reworked the whole thing to say

The Web Socket Endpoint represents an object that can handle websocket conversations. Developers may extend this class in order to implement a programmatic websocket endpoint. The Endpoint class holds lifecycle methods that may be overridden to intercept websocket open, error and close events. By implementing the onOpen method, the programmatic endpoint gains access to the Session object, to which the developer may add MessageHandler implementations in order to intercept incoming websocket messages. Each instance of a websocket endpoint is guaranteed not to be called by more than one thread at a time per active connection.

If deployed as a client endpoint, it will be instantiated once for the single connection to the server.

When deployed as a server endpoint, the implementation uses the ServerEndpointConfig.Configurator.getEndpointInstance(java.lang.Class<T>) method to obtain the endpoint instance it will use for each new client connection. If the developer uses the default ServerEndpointConfig.Configurator, there will be precisely one endpoint instance per active client connection. Consequently, in this typical case, when implementing/overriding the methods of Endpoint, the developer is guaranteed that there will be at most one thread calling each endpoint instance at a time.

If the developer provides a custom ServerEndpointConfig.Configurator which overrides the default policy for endpoint instance creation, for example, using a single Endpoint instance for multiple client connections, the developer may need to write code that can execute concurrently.





[WEBSOCKET_SPEC-81] Consider using servlet security annotations to configure authorization and connection encryption Created: 21/Dec/12  Updated: 07/Feb/13  Due: 08/Feb/13  Resolved: 07/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: New Feature Priority: Major
Reporter: dannycoward Assignee: Unassigned
Resolution: Won't Fix Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

as synopsis. In addition to being able to configure this in the web.xml, which is already there.



 Comments   
Comment by dannycoward [ 02/Feb/13 ]

This is theoretically possible, however, I'm going to propose we look at this in the next version due to time constraints.

Comment by dannycoward [ 07/Feb/13 ]

Since we already have a basic security mechanism via the web.xml that we can use, and since we want to take some time to study more use cases for websocket-specific security, we're going to defer this feature to a future version.

It may be that we will want websocket-specific annotations for this.

This has been added to the wish-list for version 2.





[WEBSOCKET_SPEC-80] Semantics of undeploy of a websocket Created: 21/Dec/12  Updated: 05/Feb/13  Due: 08/Feb/13  Resolved: 05/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: New Feature Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

Should containers call onClose() if they decide to close the connection? (in the absence of a close frame) Or should the developer use some other lifecycle to know the container is closing the connection.
Is the container/sys admin allowed to undeploy an endpoint if an endpont is being badly behaved - e.g. throwing runtime exceptions every time its called.



 Comments   
Comment by dannycoward [ 03/Feb/13 ]

We've decided onClose() is called whether the local container closes it or the remote peer sends the close frame.

Awaiting more info on the undeploy situation from the reporter.

Comment by dannycoward [ 05/Feb/13 ]

On undeploy, we are not specifying this process for this version. So the specification doesn't need to say anything around the reasoning or circumstances of undeploying applications.

Comment by dannycoward [ 05/Feb/13 ]

This is now resolved.





[WEBSOCKET_SPEC-79] Deployment on the server by instance Created: 21/Dec/12  Updated: 28/Feb/13  Due: 08/Feb/13  Resolved: 28/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: New Feature Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
is related to WEBSOCKET_SPEC-114 Programmatic deployment of server end... Resolved
Tags: v014

 Description   

ALlow developers to create their own instances of websocket endpoints and deploy them (singletons)



 Comments   
Comment by dannycoward [ 17/Jan/13 ]

Also, as Rossen points out, the ServletContext in Servlet 3.0 allows registration of Servlets and Filters by instance and by type.

Note: the 'default' mode for server websockets is to use a new instance per client connection. So will the singleton model be ok for the deploy-by-instance case ?

Comment by dannycoward [ 28/Feb/13 ]

eg seems to be ok with add getEndpointInstance() to ServerEndpointConfig.Configurator which will address this.

Comment by dannycoward [ 28/Feb/13 ]

v014 allows the developer to control the instance creation of endpoints using the

ServerEndpointConfig.Configurator.getEndpointInstance(Class<T> endpointClass) call.





[WEBSOCKET_SPEC-77] javadoc formatting issues Created: 17/Dec/12  Updated: 21/Dec/12  Resolved: 21/Dec/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: jitu Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v011

 Description   

Use tags like <pre> etc formatting instead of &nbsp, <br> etc.

For example, WebSocketPathParam looks like this

&nbsp@WebSocketEndpoint("/bookings/{guest-id}");<br>
 * public class BookingServer {<br><br>
 * <p/>
 * &nbsp&nbsp@WebSocketMessage<br>
 * &nbsppublic void processBookingRequest(@WebSocketPathParam("guest-id") String guestID, String message, Session session) {<br>
 * &nbsp&nbsp&nbsp// process booking from the given guest here<br>
 * &nbsp}<br>
 * }

It can be better written as

* <pre>
* <code>
* &#64;WebSocketEndpoint("/bookings/{guest-id}")
* public class BookingServer {
*     &#64;WebSocketMessage
*     public void processBookingRequest(@WebSocketPathParam("guest-id") String guestID, String message, Session session) {
*         // process booking from the given guest here
*     }
* }
* </code>
* </pre>


 Comments   
Comment by dannycoward [ 21/Dec/12 ]

reformatted for v011





[WEBSOCKET_SPEC-76] Allow implementations to batch multple messages for sending Created: 15/Dec/12  Updated: 21/Dec/12  Resolved: 21/Dec/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v011

 Description   

Ideally this would be transparent to the developer, but we are not sure it can me.

We may need some combination of setBatchingAllowed() and an explicit flush().

Or we could arrange a special subtype of RemoteEndpoint which allows more friendly batching APIs.



 Comments   
Comment by dannycoward [ 21/Dec/12 ]

we have an api for this in v011 on RemoteEndpoint





[WEBSOCKET_SPEC-75] Consider requiring BASIC and DIGEST authentication schemes in the client container. Created: 14/Dec/12  Updated: 26/Jan/13  Due: 25/Jan/13  Resolved: 26/Jan/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Won't Fix Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

as symopsis



 Comments   
Comment by dannycoward [ 17/Jan/13 ]

Note that if we allow all client components to intercept the handshake, they have the ability to provide their own implementations of BASIC and DIGEST (and any number of other Http request/response authentication schemes) without having to require them in all implementations.

Comment by dannycoward [ 26/Jan/13 ]

We will not support this for version 1.0.

Am closing this issue and adding it to the wishlist for the next version.

Comment by dannycoward [ 26/Jan/13 ]

will consider for next version.





[WEBSOCKET_SPEC-74] Consider scoping getOpenSessions() just to the endpoint Created: 14/Dec/12  Updated: 08/Feb/13  Due: 05/Feb/13  Resolved: 08/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

i.e. just the sessions open for that endpoint.

e.g. move to Session.



 Comments   
Comment by dannycoward [ 01/Feb/13 ]

proposed to expert group

Comment by dannycoward [ 08/Feb/13 ]

I am fixing this as proposed for version 12.





[WEBSOCKET_SPEC-12] Separate send methods, byFuture, byCompletion Created: 28/Sep/12  Updated: 09/Nov/12  Due: 09/Nov/12  Resolved: 09/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

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.



 Comments   
Comment by dannycoward [ 30/Oct/12 ]

awaiting further feedback from the expert group.

Comment by dannycoward [ 09/Nov/12 ]

This is in v008





[WEBSOCKET_SPEC-11] Text Frame - partial UTF-8 sequence Created: 24/Sep/12  Updated: 09/Nov/12  Due: 09/Nov/12  Resolved: 09/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: jitu Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

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.



 Comments   
Comment by dannycoward [ 09/Nov/12 ]

We are deferring the API for extensions/data framing to a later version, so I am closing out this issue.





[WEBSOCKET_SPEC-10] Allow the API to match on URI-templates as well as the annotations Created: 21/Sep/12  Updated: 17/Nov/12  Due: 09/Nov/12  Resolved: 17/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v008

 Description   

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).



 Comments   
Comment by dannycoward [ 17/Nov/12 ]

v008 tweaks the API to allow URI-templates in the ServerEndpointConfiguration, and the documentation has been adjusted.





[WEBSOCKET_SPEC-8] Reliablity and expense of session.isActive() / container.getActiveSessions() Created: 21/Sep/12  Updated: 30/Nov/12  Resolved: 30/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: Unassigned
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

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 ?



 Comments   
Comment by Sutanu Ghosh [ 05/Oct/12 ]

I think a better name would be isOpen(). It should return true if and only if the WebSocket is open i.e. not yet closed by either endpoint.
Also this should not be about the underlying socket since the socket is still open for a while after one endpoint closes the WebSocket session.

Comment by dannycoward [ 30/Nov/12 ]

We have reworked the naming and semantics to be based on the open/close information the websocket protocol provides.

So now it is isOpen instead of isActive() and getOpenSessions() instead of getActiveSessions().





[WEBSOCKET_SPEC-7] Boostrapping websocket containers in web container and standalone Created: 21/Sep/12  Updated: 17/Nov/12  Due: 09/Nov/12  Resolved: 17/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v008

 Description   

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.



 Comments   
Comment by dannycoward [ 12/Nov/12 ]

Some notes on client-side and server-side deplotment

Server Side
automatic POJO scanning
No scan for Endpointsubclass, programmtically deploy
deploy method should work for POJO

Client Side
no scan, programmtic deployment (client needs to control when to connect)
programmtic POJO deployment.

Comment by dannycoward [ 17/Nov/12 ]

We have added the appropriate client deployment API for POJOs and Endpoints and adjusted the server API for deployment. The spec document has been updated for the WAR scanning for POJOs.





[WEBSOCKET_SPEC-3] Specification needs to distinguish better between client and server functionality Created: 21/Sep/12  Updated: 13/Dec/12  Due: 14/Dec/12  Resolved: 13/Dec/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 1
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v010

 Description   

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.



 Comments   
Comment by Sutanu Ghosh [ 05/Oct/12 ]

+1 for api usability.

It's logical to separate them since there are differences in how client and server endpoints operate.

I suggest:
javax.net.websocket - all common stuff
javax.net.websocket.client - client only
javax.net.websocket.server - server only

Comment by dannycoward [ 17/Nov/12 ]

Additional feedback: separate ClientContainer and ServerContainer out of having a common superclass. Ditto Config classes.

Comment by dannycoward [ 08/Dec/12 ]

the expert group determined that they would like web socket implementations running in application servers to be able to initiate websocket connections to other servers.

Since this functionality is what we had been referring to as 'client-only' it means that websockets running on a client platform (like a tablet) and websockets running on an application server have this behavior in common.

Only the ability to deploy websocket endpoints that await connections from multiple clients is unique to the server.

Therefore, we just need two packages: one for the common stuff + client functionality, and one for the server only functionality.

Something like

javax.websocket for the common stuff
javax.websocket.server for the server-only stuff.

So, for example, JDK 9 might include javax.websocket, but not javax.websocket.server, whereas Java EE 7 will include both javax.websocket and javax.websocket.server.

Comment by dannycoward [ 13/Dec/12 ]

Since the server profile includes the ability to initiate connections for peer to peer websockets, the 'client only' package is not needed.

We have now

javax.websocket.* - everything shared between client and server implementations
javax.websocket.server.* everything that only makes sense in a server implementation.

So Client Side (like desktop applications) will need to use javax.websocket.*.
Server Side (like web applications) will need to use both javax.websocket.* and javax.websocket.server.*.





[WEBSOCKET_SPEC-4] Ambiguous: Can multiple POJO methods be mapped to the same URI ? Created: 21/Sep/12  Updated: 04/Dec/12  Due: 16/Nov/12  Resolved: 04/Dec/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v009

 Description   

@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 ?



 Comments   
Comment by dannycoward [ 29/Oct/12 ]

Current thoughts: We can't have multiple methods handling same message, otherwise the implementation would need to copy messages, which may be very large.

You might think this would make some sense:-

@WebSocketEndpoint("/hello", decoders=

{MyAppleDecoder.class}

)
public class HelloServer {
@WebSocketMessage
public void processGreeting(String message)

{ .. }

@WebSocketMessage
public void processCommunication(Apple apple) { .. }

}

but again, the message would be consumed twice. Currently I am thinking that the onMessage and @WebSocketMessage methods consume the message, so there can only be one.

If we made such a restriction, we would need to enforce it (at deployment time). It wouldn't be very nice to try to pick which method actually won.

Comment by dannycoward [ 04/Dec/12 ]

We will restrict the model to being able to configure only one MessageHandler per native websocket message type: text, binary and Pong.





[WEBSOCKET_SPEC-5] Define relationship between HttpSession and Web Socket Sessions. Created: 21/Sep/12  Updated: 13/Dec/12  Due: 09/Nov/12  Resolved: 13/Dec/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v010

 Description   

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 ?



 Comments   
Comment by dannycoward [ 07/Dec/12 ]

1) The only association between websocket session and HttpSession is at opening handshake time. The API gives developers a convenient access to the HttpSession object at that point in time.
2) The user identity associated with the websocket Session is the user identity that was established at the opening handshake.
2) If the server decides that authorization for this websocket resource by this user identity has ended (it expired, or some logout mechanism was invoked) then the websocket implementation must immediately close the connection.

(from my read of the websocket spec, the most suitable close code for the latter is 1008).

Comment by dannycoward [ 13/Dec/12 ]

This has been updated in v010 of the spec, per my comment.





[WEBSOCKET_SPEC-47] Add checked exceptions to ClientContainer.connect and ServerContainer.publish methods. Created: 22/Oct/12  Updated: 03/Nov/12  Resolved: 03/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

Then the user knows about the failure cases.



 Comments   
Comment by dannycoward [ 30/Oct/12 ]

Here's my current thinking, which we will discuss in the expert group.

MessageHandlers and Decoders

Principles

Each message is handled by at most one message handler
Messages that are unhandled result in calls to onError/@WebSocketError callbacks so developers always know if incoming messages are not handled
Developer provided decoders are chosen before platform decoders.
If a decoder fails, the error is delivered and no more decoders are attempted.

Process

1. a whole string message arrives

a) if there is an MessageHandler.AsyncText handler - do not call it
b) if there is an MessageHandler.CharStream handler - do not call it
c) if there is a MessageHandler.Text handler handler, call it and stop, using the first developer provided Decoder.TextStream<String> or Decoder.Text<String>, if any.
d) if there is a MessageHandler.DecodedObject<T>
then try to find a Decoder.Text<T> or a Decoder.TextStream<T>. Look, in order, through developer provided ones (single list, may contain both Text and TextStream types). Then look through platform provided ones. Use the first match to decode it. If the decode works, call the MessageHandler and stop, if not, call the onError/@WebSocket method with the decode exception and stop. If no decoder is found, the message is unhandled.
Option: prefer higher level objects to lower level ones. i.e. if there is a decoder for T, and there is a MessageHandler.DecodedObject<T>, and also a MessageHandler.Text, choose the MessageHandler.DecodedObject<T>.

e) If the message is unhandled, call back on the onError/@WebSocketError method. We may need a new exception type for Unhandledmessages.

2) a whole binary message arrives: same process as 1).

3 the first piece of a chunked string message arrives.

a) if there is an MessageHandler.AsyncText handler - call it repeatedly until all the message has arrived and stop
b) if there is an MessageHandler.CharStream handler - call it with a Reader linked to the incoming parts, and stop
c) if there are MessageHandler.Text or MessageHandler.DecodedObject handlers, wait for all the string pieces to arrive, building the whole message as you go (subject to the buffer limit defined on the API). If the buffer limit is exceeded call the onError/@WebSocketError method on the endpoint. Otherwise, using the whole message, jump to the analogous steps for 1c), d) and e).

4) the first piece of a chinked binary message arrives

same process as 3) but for binary.

Comment by dannycoward [ 03/Nov/12 ]

This has now been fixed.





[WEBSOCKET_SPEC-46] Add getURI() to ClientEndpointConfigurations Created: 22/Oct/12  Updated: 03/Nov/12  Due: 09/Nov/12  Resolved: 03/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: Unassigned
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

Otherwise the implementation can't use it !



 Comments   
Comment by dannycoward [ 03/Nov/12 ]

This has been added in the API source repo





[WEBSOCKET_SPEC-45] ServerConfiguration.getNegotiatedExtensions Created: 20/Oct/12  Updated: 03/Nov/12  Due: 09/Nov/12  Resolved: 03/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: Unassigned
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

Make the parameter and return type List<String>, not List<Extension>

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



 Comments   
Comment by dannycoward [ 03/Nov/12 ]

Now uses strings





[WEBSOCKET_SPEC-44] Clarify default handshake negotation and corner cases Created: 19/Oct/12  Updated: 17/Nov/12  Resolved: 17/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: dannycoward Assignee: Unassigned
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v008

 Description   

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.



 Comments   
Comment by dannycoward [ 17/Nov/12 ]

There are now clarified in the javadoc for v008

Comment by dannycoward [ 17/Nov/12 ]

all clarified in the javadocs in v008





[WEBSOCKET_SPEC-43] Allow injection of API objects into client programming model Created: 17/Oct/12  Updated: 24/Jan/13  Resolved: 24/Jan/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v010

 Description   
  • 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.



 Comments   
Comment by dannycoward [ 24/Jan/13 ]

We now have the @WebSocketClient annotation.





[WEBSOCKET_SPEC-41] Consider allowing non-String types to assume the value of path parameters Created: 17/Oct/12  Updated: 17/Nov/12  Due: 16/Nov/12  Resolved: 17/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: Unassigned
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v008

 Description   

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.



 Comments   
Comment by dannycoward [ 17/Nov/12 ]

This feature has been added, spec and javadoc updated accordingly.





[WEBSOCKET_SPEC-42] @WebSocketPathParameter clarifications Created: 17/Oct/12  Updated: 08/Dec/12  Due: 16/Nov/12  Resolved: 08/Dec/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v009

 Description   
  • 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.


 Comments   
Comment by dannycoward [ 08/Dec/12 ]

We may consider bean validation for the next version - the other issues are now resolved.





[WEBSOCKET_SPEC-39] WebSocket message handling: Clarify who handles what when there are multiple encoders Created: 17/Oct/12  Updated: 04/Dec/12  Due: 09/Nov/12  Resolved: 04/Dec/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: Unassigned
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v009

 Description   

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 ?



 Comments   
Comment by dannycoward [ 29/Oct/12 ]

I'm adding the first version of a proposal which I'll send to the expert group. Nothing decided yet.

Principles

Each message is handled by at most one message handler
Messages that are unhandled result in calls to onError/@WebSocketError callbacks so developers always know if incoming messages are not handled
Developer provided decoders are chosen before platform decoders.
If a decoder fails, the error is delivered and no more decoders are attempted.

Process

1. a whole string message arrives

a) if there is an MessageHandler.AsyncText handler - call it and stop
b) if there is an MessageHandler.CharStream handler - call it and stop
c) if there is a MessageHandler.Text handler handler, call it and stop, using the first developer provided Decoder.TextStream<String> or Decoder.Text<String>, if any.
d) if there is a MessageHandler.DecodedObject<T>
then try to find a Decoder.Text<T> or a Decoder.TextStream<T>. Look, in order, through developer provided ones (single list, may contain both Text and TextStream types). Then look through platform provided ones. Use the first match to decode it. If the decode works, call the MessageHandler and stop, if not, call the onError/@WebSocket method with the decode exception and stop.

e) If the message is unhandled, call back on the onError/@WebSocketError method. We may need a new exception type for Unhandledmessages.

2) a whole binary message arrives: same process as 1).

3 the first piece of a chunked string message arrives.

a) if there is an MessageHandler.AsyncText handler - call it repeatedly until all the message has arrived and stop
b) if there is an MessageHandler.CharStream handler - call it with a Reader linked to the incoming parts, and stop
c) if there are MessageHandler.Text or MessageHandler.DecodedObject handlers, wait for all the string pieces to arrive, building the whole message as you go (subject to the buffer limit defined on the API). If the buffer limit is exceeded call the onError/@WebSocketError method on the endpoint. Otherwise, using the whole message, jump to the analogous steps for 1c), d) and e).

4) the first piece of a chinked binary message arrives

same process as 3) but for binary.

Comment by dannycoward [ 04/Dec/12 ]

We are restricting the model to being able to configure only one MessageHandler per native websocket message type: text, binary and Pong.





[WEBSOCKET_SPEC-38] Clarify error conditions on connections in the API Created: 17/Oct/12  Updated: 14/Dec/12  Resolved: 14/Dec/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v010

 Description   

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 ?



 Comments   
Comment by dannycoward [ 14/Dec/12 ]

all categories are now clarified in the spec.

Decode exceptions are checked to allow explicit handing of malformed messages. Websocket endpoints can typically survive such cases, and using the onError mechanism, its likely that the websocket can still do something useful with the raw message even when the decoder has a problem.





[WEBSOCKET_SPEC-35] Remove leading / requirement from paths Created: 17/Oct/12  Updated: 17/Nov/12  Due: 16/Nov/12  Resolved: 17/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v008

 Description   

Because it is visual noise.

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



 Comments   
Comment by dannycoward [ 16/Nov/12 ]

We will not change this: we will stay consistent with the servlet API and specification, rather than align with JAX-RS.

Future specs may use paths with no leading slash for something else.

Comment by dannycoward [ 17/Nov/12 ]

We will retain the leading slashes consistent with the servlet spec url-pattern.





[WEBSOCKET_SPEC-37] Consider changing number of endpoint instances Created: 17/Oct/12  Updated: 10/Nov/12  Due: 09/Nov/12  Resolved: 10/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

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.



 Comments   
Comment by dannycoward [ 10/Nov/12 ]

I agree with Scott that this is a good change: to require a new instance of the Endpoint per session. It greatly simplifies the developer model in regard to having to deal with multiple threads. Ditto for the POJOs. So I propose we make this change in the next draft.

The consequences for this change are:-

1) we need to change the server publish method to take the endpoint class rather than one instance:
ServerContainer.publishServer(Endpoint e, ServerEndpointConfiguration sec) -> ServerContainer.publishServer(Class<? extends Endpoint>, ServerEndpointConfiguration sec)

2) client registration: no change - one client instance connects to one URL.

3) drop the Session parameter from Endpoint.onError, Endpoint.onClose as they are no longer necessary: the Endpoint instance gets the reference to its (single) Session instance just on the onOpen method.





[WEBSOCKET_SPEC-36] URI Path mapping: Expose path segments to the developer with an API Created: 17/Oct/12  Updated: 17/Nov/12  Due: 16/Nov/12  Resolved: 17/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v008

 Description   

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



 Comments   
Comment by dannycoward [ 17/Nov/12 ]

This API is now in v008





[WEBSOCKET_SPEC-34] Simplfy package structure Created: 17/Oct/12  Updated: 09/Nov/12  Due: 16/Nov/12  Resolved: 09/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

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.



 Comments   
Comment by dannycoward [ 09/Nov/12 ]

This has been changed as recommended.





[WEBSOCKET_SPEC-33] Consider using a type like ListenableFuture in place of the Future/CompletionHandler pattern Created: 17/Oct/12  Updated: 04/Dec/12  Resolved: 04/Dec/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v009

 Description   

See, for example, the Guava project

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



 Comments   
Comment by dannycoward [ 04/Dec/12 ]

Will not fix to a custom listener/future. The (typed) SendHandler and Future is consistent with other efforts.





[WEBSOCKET_SPEC-32] SendHandler: Consider using JDK 7 CompletionHandler instead Created: 17/Oct/12  Updated: 30/Nov/12  Due: 16/Nov/12  Resolved: 30/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

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'.



 Comments   
Comment by dannycoward [ 30/Nov/12 ]

We concluded this this would make the API more difficult to use, and we prefer our single method abstract SendHandler type because we think it will be, in addition to the typing information which is useful, easier to write as a Java lambda experssion in the future.





[WEBSOCKET_SPEC-55] Several Issues with the Session interface Created: 30/Oct/12  Updated: 30/Nov/12  Resolved: 30/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

I see several issues with the Session interface:

  • The use of type parameter is weird - session is not typed when it gets created, so how/when would the type argument be supplied? I think it should be removed. Same for the RemoteEndpoint.
  • It has setEncoders() method, but encoders come from the configuration (or annotation) - so what for? And there is no setDecoders() - seems weird. Also, there is no getEncoders(), so I can't just add to the existing set. IMHO it does not make much sense to modify decoders/encoders during the session, so I'd prefer readonly session attributes, but if that is not acceptable, it should at least be consistent.
  • I can set max message size (both binary and text), while the config has max text buffer and max binary buffer sizes. This should be synced up. And again, it is questionable IMO if it makes sense to change these for the running session, so probably getters would be good enough.
  • Session.getTimeout() vs. Container.getMaxSessionIdleTimeout() - should the names of these two methods be the same?
  • why does getMessageHandlers() return an unmodifiable copy, while there are methods for adding/removing message handlers? Session would be running in a single thread (unless user explicitly spawns another one), so there should be no concurrency issues, no?
  • getRemoteL() method does not make any sense to me. The type parameter in the method is taken from the type argument of Session. So why does user have to pass Class as a parameter. Moreover, as I mentioned in the first bullet, I don't think this is a good use of the type parameter - IMO this method should be removed.
  • getParameterMap() should be immutable, but returns arrays as values - it is not possible to make arrays immutable, so should rather return Map<String, List<String>>. Also simply calling it getParameters() may be better.
  • still missing Map<String, Object> getProperties() method for storing session-related data.

And one more

  • missing Map<String, String> getPathParameters() method

(These from Martin)



 Comments   
Comment by dannycoward [ 30/Nov/12 ]

These issues have all been resolved in v009

Comment by dannycoward [ 30/Nov/12 ]

fixed in v009





[WEBSOCKET_SPEC-54] @WebSocketEndpoint(decoders/encoders) signature Created: 30/Oct/12  Updated: 17/Nov/12  Resolved: 17/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: jitu Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v008

 Description   

Currently, decoders annotation element is defined as follows:
public Class[] decoders() default {};

I think it should be:
public Class<? extends Decoder>[] decoders() default {};

similarly, for encoders



 Comments   
Comment by dannycoward [ 30/Oct/12 ]

This looks reasonable. I will propose to fix as proposed.

Comment by dannycoward [ 17/Nov/12 ]

This has been added - thanks !





[WEBSOCKET_SPEC-53] Endpoint class qualifiers for @WebSocketEndpoint Created: 26/Oct/12  Updated: 05/Feb/13  Due: 05/Feb/13  Resolved: 05/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: jitu Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

Define whether the endpoint class needs to be public, or final ? Can it be abstract etc ? Also make sure it is conformant with other EE specs.



 Comments   
Comment by dannycoward [ 30/Oct/12 ]

See section 4.1 of the spec which refers additionally to 7.3.1.

Jitu: Let me know if you think anything is missing, I'm following standard practice with, for example, JAX-RS.

Comment by jitu [ 31/Oct/12 ]

JAX-RS resources need not have zero-org constructors. See chapter 3.1.2. But it is odd that it doesn't specify any other requirements.

From the definition, the following is allowed (but it cannot be instantiated)

@WebSocketEndpoint
abstract class A {
public A() {
}
}

Comment by dannycoward [ 31/Jan/13 ]

OK. We certainly can't have non-public abstract classes.

"The class must be public, concrete, and have a public no-args constructor. The class may or may not be final, and may or may not have final methods."

Let me know if there are other types you think we have to allow for v 1.0 as a priority.

Comment by dannycoward [ 05/Feb/13 ]

What I proposed has been out to the expert group with no comment, so I am closing this out.

We might look at expanding the possibilities in the next version, but I think this is clear and simple for this version.





[WEBSOCKET_SPEC-52] Define inheritance semantics for annotations Created: 26/Oct/12  Updated: 16/Feb/13  Due: 25/Jan/13  Resolved: 16/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: jitu Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012, v013

 Description   

Define inheritance semantics for annotations. JSR 250 has guidelines. For e.g
@WebSocketEndpint
public Class A {
}

public Class B extends A {
}

can B be an endpoint etc ? Similarly for all other annotations



 Comments   
Comment by dannycoward [ 16/Nov/12 ]

It seems best to follow the guidelines for JSR 250: the WebSocket annotations only affect the class which carries them. No class that inherits from a WebSocket annotation can 'inherit' the behavior marked by the annotation.

Comment by dannycoward [ 17/Jan/13 ]

We will need to define a deployment error for applications that mistakenly try to use inheritance, and also point out that the SCI scanning will need to discard subclasses of classes marked @WebSocketEndpoint in the scan (currently, such classes will be picked up).

Comment by dannycoward [ 26/Jan/13 ]

This is clarified in v012

Comment by stepan.kopriva [ 12/Feb/13 ]

I was searching for the info in documentation in section 6.2, but I didn't find any restrictions on scanning

Comment by dannycoward [ 13/Feb/13 ]

take a look at 4.8 in v012, I'd put a note about scanning there.

In the v013 I put in a reference to 4.8 from section 6.2. Does that fix it ?

Comment by dannycoward [ 16/Feb/13 ]

OK this was already documented about the scan having to throw away subclasses in 4.8. I've also referenced it from 6.2 as well - so I'm closing this one...





[WEBSOCKET_SPEC-51] Unify annotation and programmatic API programming models Created: 26/Oct/12  Updated: 17/Nov/12  Resolved: 17/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: jitu Assignee: Unassigned
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v008

 Description   

There needs to be one programming model. This will help to write an endpoint class and be deployed in standalone or Java EE environments.

The endpoint class can be based on the annotations.
@WebSocket("/echo")
public class Echo {
...
}

1. The deployment in EE happens via DD(if anything needs to be configured/overwritten what is there in annotations). Many cases DD is optional. And we don't have to do DD in the first release. Just war the endpoints, deploy the war to app server.

2. In the standalone case a deployment is driven by a programmatic API to configure things(if any). It will take the same endpoint class (which is annotated) that worked in EE. Annotation processing is happening only one time and saying that we don't use annotated endpoints for standalone deployment doesn't make sense. For e.g see javax.xml.ws.Endpoint class for JAX-WS standalone deployment. In this case,

Endpoint e = Endpoint.publish("ws://localhost:8080/echo", Echo.class) // Same class with annotations
...
e.stop();

Of course, certain features that are available in EE cannot be done(or optional) in standalone. JAX-WS/JAX-RS followed this programming model successfully. This will help moving things from one deployment model to another easily. Easy to test. Developers don't have to learn two programming models.



 Comments   
Comment by dannycoward [ 17/Nov/12 ]

See the comment for TYRUS-14 - we will continue with POJOs and Endpoint subclasses.

We have a deployment API for client and server which meets the needs of developers.

We scan WAR files for POJOs, no requirement for any other scanning.

Comment by dannycoward [ 17/Nov/12 ]

Resolved in v008.





[WEBSOCKET_SPEC-50] Do we need ContainerProvider.getServerContainer() ? Created: 25/Oct/12  Updated: 17/Nov/12  Due: 09/Nov/12  Resolved: 17/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v008

 Description   

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 ?



 Comments   
Comment by dannycoward [ 17/Nov/12 ]

We floated the idea of using the ServiceLoader, but this way seems cleaner and consistent with other specs.





[WEBSOCKET_SPEC-49] Consider merging Endpoint with Endpoint configuration Created: 25/Oct/12  Updated: 30/Nov/12  Due: 16/Nov/12  Resolved: 30/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

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.



 Comments   
Comment by dannycoward [ 30/Nov/12 ]

We will not fix this. At one point in the design there was a rational argument for it (simplicity), but now we have one config per logical endpoint and one endpoint instance per connection, it no longer is possible





[WEBSOCKET_SPEC-30] API suggestions pot pourri Created: 12/Oct/12  Updated: 14/Dec/12  Resolved: 14/Dec/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v010

 Description   

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<T>, PartialMessageHandler<T> 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 <M> 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


 Comments   
Comment by dannycoward [ 14/Dec/12 ]

All these issues are resolved or already tracked.
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?
(already issue for this.)
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?
(Will not change this, two modes explicitly requested.)

too many MessageHandler classes. Why can't we simply have MessageHandler<T>, PartialMessageHandler<T> and PongHandler and decide based on the type argument which message handler should be called for a given message?
(fixed in v008)
for async operations, no way to specify timeouts?
(already an issue for this)
why is RemoteEndpoint capable of sending only one type of object? Why can't it simply have a single <M> send(M message) method for sending objects of any kind instead of having sendString(), sendObject(), sendBytes() and getSendStream()?
(We are balancing usability with abstractness)
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.
(this is now in)
should ServerContainer.publishServer() be renamed to publishEndpoint()? Since that's what it seems to do.
(v010 has a new deployment mechanism, this method no longer exists)
<done>
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
(now consistent)





[WEBSOCKET_SPEC-29] Clarify certain lifecycle cases onOpen/onClose/onError Created: 12/Oct/12  Updated: 17/Nov/12  Resolved: 17/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: Unassigned
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v008

 Description   

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?


 Comments   
Comment by dannycoward [ 17/Nov/12 ]

This has been simplified in version 008.

Comment by dannycoward [ 17/Nov/12 ]

This rather confusing piece is clarified in the specification v008.





[WEBSOCKET_SPEC-28] Use annotations in other settings Created: 12/Oct/12  Updated: 17/Nov/12  Resolved: 17/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v008

 Description   

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



 Comments   
Comment by dannycoward [ 17/Nov/12 ]

v008 clarifies the bootstrapping of POJOs client and server and adds a client annotation.





[WEBSOCKET_SPEC-27] Clean up specifiction of allowable parameters on @WebSocketMessage methods Created: 12/Oct/12  Updated: 04/Dec/12  Resolved: 04/Dec/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: Unassigned
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v009

 Description   

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.



 Comments   
Comment by dannycoward [ 25/Oct/12 ]

Specifically: allow all types for which there are decoders to be allowed here, and also the async callbacks.

Comment by dannycoward [ 04/Dec/12 ]

fixed per comment in upcoming v009





[WEBSOCKET_SPEC-26] Spec document: formatting and typos Created: 12/Oct/12  Updated: 03/Nov/12  Resolved: 03/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: Unassigned
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

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


 Comments   
Comment by dannycoward [ 03/Nov/12 ]

this is now fixed in the spec document.





[WEBSOCKET_SPEC-24] Endpoint mapping: what happens when paths overlap ? Created: 12/Oct/12  Updated: 04/Dec/12  Due: 16/Nov/12  Resolved: 04/Dec/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v009

 Description   

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 ?



 Comments   
Comment by dannycoward [ 04/Dec/12 ]

This will be an application deployment error.





[WEBSOCKET_SPEC-23] Remove requirement for leading slash on @WebSocketEndpoint.value() Created: 12/Oct/12  Updated: 17/Nov/12  Due: 16/Nov/12  Resolved: 17/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v008

 Description   

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



 Comments   
Comment by dannycoward [ 17/Nov/12 ]

we'll keep the slash per comment





[WEBSOCKET_SPEC-25] Define which encoders/decoders are supported by default Created: 12/Oct/12  Updated: 21/Dec/12  Due: 09/Nov/12  Resolved: 21/Dec/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v011

 Description   

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.



 Comments   
Comment by dannycoward [ 02/Nov/12 ]

we've had a suggestion floating around for a while that we'd make the set of platform decoders and encoders 'consistent with JAX-RS'. Its not yet clear to me what that means. JAX-RS 1.1 defines the following list of java objects that can be created from a string (e.g. this is the list from @FormParam, the others are similar:-

Be a primitive type
Have a constructor that accepts a single String argument
Have a static method named valueOf or fromString that accepts a single String argument (see, for example, Integer.valueOf(String))
Be List<T>, Set<T> or SortedSet<T>, where T satisfies 2 or 3 above. The resulting collection is read-only.

From this I can see that we could say JSR 356 has to support platform Decoders for 1, 2 and 3.

We could define Encoders for 1. I don't see a standard encoding for objects of type 2, 3.

Also, I presume that 4. collections, this means the JAX-RS container parses from a string which uses a well-defined semantic for lists (like form params). We do not have this in web sockets, and I don't think defining list-delimiters for web socket messages that mean a collection of something is our job to do. So I don't see a way we could support 4 either for encoding or decoding.

So, the proposal for us seems to boil down to supporting 1. primitive types and the boxed versions thereof for encoding and decoding, and supporting 2 and 3 for decoders only.

Comment by dannycoward [ 21/Dec/12 ]

This has been resolved: Java primitive types for encoders and decoders.





[WEBSOCKET_SPEC-22] Deployment: No need to raise an error for annotations that are placed at the wrong level (method/class/method param) Created: 12/Oct/12  Updated: 03/Nov/12  Resolved: 03/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

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



 Comments   
Comment by dannycoward [ 30/Oct/12 ]

Will fix by removing the deployment time requirement, and will check the annotations are defined correctly such that the compiler can reject any code with annotations at the wrong level.

Comment by dannycoward [ 03/Nov/12 ]

This is now fixed in the specification text





[WEBSOCKET_SPEC-20] API issues: long list of smaller issues to fix Created: 12/Oct/12  Updated: 03/Nov/12  Due: 09/Nov/12  Resolved: 03/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

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/



 Comments   
Comment by dannycoward [ 30/Oct/12 ]

awaiting further feedback from expert group

Comment by dannycoward [ 03/Nov/12 ]

These are fixed in API repo





[WEBSOCKET_SPEC-18] MessageHandler: Make the super-interface of all the MessageHandlers hold the lowest level onMessage method (onMessage(ByteBuffer bb, boolean last) Created: 12/Oct/12  Updated: 17/Nov/12  Resolved: 17/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v008

 Description   

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.)



 Comments   
Comment by dannycoward [ 17/Nov/12 ]

We have refactored the MessageHandlers to a more suitable hierarchy.

Comment by dannycoward [ 17/Nov/12 ]

CLosed per the last comment on this issue.





[WEBSOCKET_SPEC-17] Blocking or Asynchronous: Configuration.connectToServer and Configuration.publishEndpoint ? Created: 12/Oct/12  Updated: 14/Dec/12  Due: 16/Nov/12  Resolved: 14/Dec/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Dependency
depends on WEBSOCKET_SPEC-64 Calirify application deployment seman... Resolved
Tags: v010

 Description   

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



 Comments   
Comment by dannycoward [ 14/Dec/12 ]

This has been clarified in the spec.

On the server we use a JAX-RS like scheme: a mix of web container scanning of the WAR files to find endpoints, together with a definition of an ApplicationConfig class that developers can implement if they want finer grained control.





[WEBSOCKET_SPEC-15] Websocket sessions: how do they behave in a distributed server environment Created: 12/Oct/12  Updated: 14/Dec/12  Due: 14/Dec/12  Resolved: 14/Dec/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v010

 Description   

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.



 Comments   
Comment by dannycoward [ 14/Dec/12 ]

updated in v10





[WEBSOCKET_SPEC-14] Should only be able to create WebSockets using POJOs and Annotations Created: 12/Oct/12  Updated: 17/Nov/12  Due: 09/Nov/12  Resolved: 17/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

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).



 Comments   
Comment by dannycoward [ 16/Nov/12 ]

We will not remove either of the two modes.

We have had feedback that developers like to be able to do programmatic endpoints as well as annotations, even if some people believe that annotations should be the only mode.

As much as the EE programming model is focused around annotations nowadays, there are still many developers who prefer an API approach. Allowing other websocket frameworks to layer on top of our standard Endpoint API is going to be a big plus. We'd rather than kind of invention happen on top of our APIs than away from them.

Comment by dannycoward [ 17/Nov/12 ]

We will keep both POJOs and Endpoints per the comment





[WEBSOCKET_SPEC-64] Calirify application deployment semantics Created: 30/Nov/12  Updated: 14/Dec/12  Due: 14/Dec/12  Resolved: 14/Dec/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Dependency
blocks WEBSOCKET_SPEC-17 Blocking or Asynchronous: Configurati... Resolved
Tags: v010

 Description   

Current scheme is a mix of scanning and programmatic deployment

We are exploring a more webcontainer friendly and efficient manner, using an application config class in the expert group.



 Comments   
Comment by dannycoward [ 14/Dec/12 ]

This has been clarified in the spec.

On the server we use a JAX-RS like scheme: a mix of web container scanning of the WAR files to find endpoints, together with a definition of an ApplicationConfig class that developers can implement if they want finer grained control.





[WEBSOCKET_SPEC-13] Provide ability to attach arbitrary objects to a Session Created: 05/Oct/12  Updated: 30/Nov/12  Due: 16/Nov/12  Resolved: 30/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: Sutanu Ghosh Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

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()



 Comments   
Comment by dannycoward [ 30/Nov/12 ]

We are adding this for v009 of the spec, look out for it soon !

Comment by dannycoward [ 30/Nov/12 ]

adding this ability for v009 draft





[WEBSOCKET_SPEC-57] @WebSocketError is missing Created: 08/Nov/12  Updated: 17/Nov/12  Resolved: 17/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: arungupta Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v008

 Description   

@WebSocketError is missing. This is required to map to an error message for the annotation-driven programming model



 Comments   
Comment by dannycoward [ 17/Nov/12 ]

Arun - wasn't clear which spec version version this was missing from, but its definitely there in v008 !





[WEBSOCKET_SPEC-56] Consider moving the encoders list to the same place where the MessageHandlers are Created: 08/Nov/12  Updated: 08/Dec/12  Resolved: 08/Dec/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: Unassigned
Resolution: Won't Fix Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

By the way, it seems a mismatch that the MessageHandler is assigned in the session, but the decoder is assigned in the EndpointConfiguration. I'd think their config should be at the same place (and setDecoders set in the same place as setEncoders is.)



 Comments   
Comment by dannycoward [ 08/Dec/12 ]

will not fix. The API works how we need it to.





[WEBSOCKET_SPEC-61] Specify: ignore trailing slash on paths throughout API. Created: 14/Nov/12  Updated: 17/Nov/12  Resolved: 17/Nov/12

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v008

 Description   

As synopsis



 Comments   
Comment by dannycoward [ 17/Nov/12 ]

We will ignore them, consistent with other specs.





[WEBSOCKET_SPEC-58] Thorough list of smaller API, javadoc, spec suggestions based on the EDR draft Created: 13/Nov/12  Updated: 26/Feb/13  Resolved: 26/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v014

 Description   

This from Joakim Erdfelt from Intalio

1) ServerContainer and ServerEndPointContainer are duplicate classes (removed in v008)
2) DefaultClientConfiguration.getExtensions() will always return null. (fixed in v008)
3) CloseReason.CloseCodes is missing 2 status codes. (these have been added in v008)
SERVICE_RESTART(1012)
TRY_AGAIN_LATER(1013)
They were proposed and accepted after RFC 6455 was final.
Discussion here ...
https://www.ietf.org/mail-archive/web/hybi/current/msg09649.html
They are formally registered at
https://www.iana.org/assignments/websocket/websocket.xml#close-code-number-rules
4) There needs to be clearer javadoc on the CloseReason.CloseCodes as to the various rules around them. (Can only be sent by Server, only by Client, cannot be sent over connection, etc ...)
5) Timeouts are declared as seconds, but in other network protocols timeouts are defined as milliseconds. Would recommend that we stick with the millisecond level accuracy. (milliseconds in v008)
Example: http://docs.oracle.com/javase/6/docs/api/java/net/Socket.html#setSoTimeout(int)
6) Typo in ClientContainer.getMaxTextMessageBufferSize() "wed socket" (fixed v008)
7) ClientEndpointConfiguration needs .setCookieStore(java.net.CookieStore) to satisfy authenticated user requirements.
8) ClientEndpointConfiguration getter such as .getDecoders() and .getExtensions() (and probably all API getters) should be clear as to if they are allowed to return null, and if they are collections, should they always return a collection object, even if its empty? I see language about returning modifiable collections and whatnot, that's of great help, lets get more detailed please. (some fixed in v008, more to do)
9) Need clarification if various collection setters, like ClientEndpointConfiguration.setEncoders() should use the collection as-is (helping with memory, but not with threading) or should copy the collection entries (if so, shallow or deep copy)?
10) Various setExtension() .getExtension() javadoc should indicate if the <String> being referenced is a full ANBF extension (extension-token ";" extension-param), or just the extension name. (RFC-6455, Section
Consider an ExtensionConfig interface instead.
Example:
http://git.eclipse.org/c/jetty/org.eclipse.jetty.project.git/tree/jetty-websocket/websocket-api/src/main/java/org/eclipse/jetty/websocket/api/extensions/ExtensionConfig.java?h=ws-refactor
11) The default Session.getRemote() should use what <T> implementation? <Object>? (v008 removes T, was providing no extra checking for developers)
12) Creating a new RemoteEndpoint for a difference in Object type is overly complex, how about ObjectSender RemoteEndpoint.getObjectSender(Foo.class) as an alternative approach? (thinking about this)
That way we can perform the "am in the middle of a message?" check on that, the Writer, or the OutputStream to see if we can even start sending another message (yet).
Keep in mind that if .getSendWriter() is active, no other .send*() method can be used until that Writer is closed (causing a FIN=true on the message)
13) HandshakeRequest.getParameterMap() should include javadoc indicating that it is only URI Query parameters from GET requests only that will be returned. (All other request methods cannot be Upgraded)
14) HandshakeRequest.getRequestURI() returns a URI object, yet the servlet-api returns a String object of the same method signature. (whoops, can't just wrap HttpServletRequest, have to copy the values now)
http://docs.oracle.com/javaee/6/api/javax/servlet/http/HttpServletRequest.html#getRequestURI()
15) HandshakeRequest.getRequestURI() should include javadoc to indicate what sort of information will be returned by this getter. For example, in the servlet-api, this will NOT return the query portion.
16) Session.getInactiveTime() (and setInactiveTime()), need javadoc to indicate how if this affect physical or logical connections? (for example, on mux, the logical connection would be the place for this)
17) Need some language on @WebSocketPathParam that this is only for server side websockets, not client side.
18) The CloseReason.reasonPhrase has a limit on how big can be. (125 UTF8 bytes to be exact)
Should the constructor truncate? or fail if the reason phrase is too big?
(I favor truncation)



 Comments   
Comment by dannycoward [ 17/Nov/12 ]

Many of these issues have been integrated into v008. There are still a few left, so I am keep this issue open until v009.

Comment by dannycoward [ 26/Feb/13 ]

these issues are all now resolved in v014





[WEBSOCKET_SPEC-107] Missing configuration for Extensions in WebSocketConatiner Created: 15/Jan/13  Updated: 31/Jan/13  Resolved: 31/Jan/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: stepan.kopriva Assignee: Unassigned
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

The WebSocketContainer has got a method Set<Extension> getInstalledExtensions(); There is no way how to configure what Extensions are installed on the container.



 Comments   
Comment by dannycoward [ 31/Jan/13 ]



This was one of the features we dropped as part of the extensions SPI. So we might do it for the next release, but for this release, implementations, if they support any extensions (which they do not have to do), will have to do this in an implementation specific way.





[WEBSOCKET_SPEC-103] DefaultServerConfiguration used in @WebSocketEndpoint Created: 10/Jan/13  Updated: 16/Feb/13  Due: 08/Feb/13  Resolved: 16/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Pavel Bucek Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v013

 Description   

@WebSocketEndpoint javadoc:

    /**
     * The custom configuration class that the developer would like to use
     * to configure new instances of this endpoint.
     *
     * @return the custom configuration class.
     */
    public Class<? extends DefaultServerConfiguration> configuration();

How should I implement my custom DefaultServerConfiguration? Seems like I have to call constructor (no-arg is private):

    public static class MyDefaultServerConfiguration extends DefaultServerConfiguration {

        public MyDefaultServerConfiguration(Class<? extends Endpoint> endpointClass, String path) {
            super(endpointClass, path);
        }
    }

what should be present in path argument? Why should I put it there if its available from @WebSocketEndpoint anotation? (value is path and annotated class is endpointClass). Is this supposed to be application wide configuration? It needs to be clear in javadoc.

Additionally, if its per endpoint, shouldn't that be DefaultServerEndpointConfiguration?

And last but not least - why is Default implementation forced here? User might want to provide its own - just and interface would look better for me.



 Comments   
Comment by Pavel Bucek [ 11/Jan/13 ]

spec must define what set of endocers/decoders should be used

  • only from provided configuration?
  • only from @WebSocketEndpoint?
  • merge? (in what order?)
Comment by jitu [ 11/Jan/13 ]

Yes. Alternatively, we can also think of giving information only once(perhaps, by removing encoders/decoders from the annotation)

Comment by dannycoward [ 16/Feb/13 ]

I think all these messy issues in the old api are now fixed in the new one.





[WEBSOCKET_SPEC-102] CloseReason.CloseCodes Created: 09/Jan/13  Updated: 01/Feb/13  Resolved: 01/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Pavel Bucek Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

there is no way how I could create CloseCode from code (integer).

Please add CloseCodes.fromCode(int code).



 Comments   
Comment by dannycoward [ 01/Feb/13 ]

Hey Pavel:

CloseReason cr = new CloseReason(CloseReason.CloseCodes.NORMAL_CLOSURE, "bye bye");

All the integers you should be using should be already in CloseReason.CloseCodes

  • does that cover it - d ?
Comment by Pavel Bucek [ 01/Feb/13 ]

I need to create it from incoming integer value, to create close reason which will be put as a parameter to onClose() method.

I would expect something like what we have in TyrusEndpoint

    /**
     * Creates {@link javax.websocket.CloseReason.CloseCode} from given integer value.
     * <p/>
     * Present only for our convenience, should be removed once http://java.net/jira/browse/WEBSOCKET_SPEC-102 is
     * resolved.
     *
     * @param code close code.
     * @return {@link javax.websocket.CloseReason.CloseCode} instance corresponding to given value or newly created
     *         anonymous class if code is not present in {@link javax.websocket.CloseReason.CloseCodes} enumeration.
     * @throws IllegalArgumentException when code is smaller than 1000 (not used) or bigger than 4999. See RFC-6455,
     *                                  section 7.4 for more details.
     */
    public static CloseReason.CloseCode getCloseCode(final int code) {
        if (code < 1000 || code > 4999) {
            throw new IllegalArgumentException();
        }

        switch (code) {
            case 1000:
                return CloseReason.CloseCodes.NORMAL_CLOSURE;
            case 1001:
                return CloseReason.CloseCodes.GOING_AWAY;
            case 1002:
                return CloseReason.CloseCodes.PROTOCOL_ERROR;
            case 1003:
                return CloseReason.CloseCodes.CANNOT_ACCEPT;
            case 1004:
                return CloseReason.CloseCodes.RESERVED;
            case 1005:
                return CloseReason.CloseCodes.NO_STATUS_CODE;
            case 1006:
                return CloseReason.CloseCodes.CLOSED_ABNORMALLY;
            case 1007:
                return CloseReason.CloseCodes.NOT_CONSISTENT;
            case 1008:
                return CloseReason.CloseCodes.VIOLATED_POLICY;
            case 1009:
                return CloseReason.CloseCodes.TOO_BIG;
            case 1010:
                return CloseReason.CloseCodes.NO_EXTENSION;
            case 1011:
                return CloseReason.CloseCodes.UNEXPECTED_CONDITION;
            case 1012:
                return CloseReason.CloseCodes.SERVICE_RESTART;
            case 1013:
                return CloseReason.CloseCodes.TRY_AGAIN_LATER;
            case 1015:
                return CloseReason.CloseCodes.TLS_HANDSHAKE_FAILURE;
        }

        return new CloseReason.CloseCode() {
            @Override
            public int getCode() {
                return code;
            }
        };
    }
Comment by dannycoward [ 01/Feb/13 ]

ok, got it. will add - d

Comment by dannycoward [ 01/Feb/13 ]

fixed as suggested.





[WEBSOCKET_SPEC-101] Programmatic MessageHandler registration Created: 09/Jan/13  Updated: 26/Feb/13  Due: 05/Feb/13  Resolved: 26/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Pavel Bucek Assignee: dannycoward
Resolution: Works as designed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012, v014

 Description   
  • Session.addMessageHandler and @WebSocketMessage specify different rules (limits) to registered MessageHandlers. This should be unified if you want to be able to achieve same results via programmatic and annotated case.
  • MessageHandler and Session javadoc sometimes mention "listener" instead of "handler" when describing MessageHandler
  • Session.addMessageHandler does specify rules which are applicable to MessageHandler.Basic (at least it seams to), what about MessageHandler.Async (there is no specification of Async types)? It does not mention "decodable" type at all.
  • Threading issues needs to be resolved (still TBDs in javadoc)


 Comments   
Comment by dannycoward [ 02/Feb/13 ]

Making sure I'm understanding this, first bullet:-

From WebSocketMessage:-
"Each websocket

  • endpoint may only have one message handling method for each of the native websocket message formats: text, binary and pong. Methods
  • using this annotation are allowed to have
  • parameters of types described below, otherwise the container will generate an error at deployment time."

from Session.addMessageHandler:-

"Only one message handler per

  • native websocket message type may be added: a maximum of one for handling incoming text messages,
  • a maximum of one for handling incoming binary messages, and a maximum of one for handling incoming pong
  • messages. Adding more than one of any one type will result in an illegal state exception being thrown
  • by this method."

...perhaps its the language (or a different version), but the limits are the same ?

second bullet: thanks, got them all. I think it best to say the removal may be blocked if the handler is in the middle of processing something ?

third bullet: The language I used for message handlers is general: a message handler processing text messages could be a MessageHandler.Basic<String>, MessageHandler.Async<String>, or MessageHandler.Basic<Apple> where there is an apple decoder for text messages. so I think that covers it ?

last bullet: see above on threading.

Comment by Pavel Bucek [ 04/Feb/13 ]

ad 1) what I'd like to see is have this unified. I still think there is some difference between Session.addMessageHandler and @WebSocketMessage javadoc, but it might be just on my side. Anyway if Session.addMessageHandler javadoc would contain just simple statements about params + reference to @WebSocketMessage, it would be more readable (for me) because I wouldn't need to "parse" twice same info.

ad 3) see 1).. basically I see some definitions/declarations - I might be just too strict when reading the documentation, but I kind of need to do that - if not anything else, I'm sure I will need to defend my implementation when it will be confronted with QA developer(s).

Comment by dannycoward [ 04/Feb/13 ]

OK fair enough, its good to tighten this up! I've cleaned this up so there should be no room for interpretation.

MessageHandler.Basic and MessageHandler.Async explicitly define which types T are for text, binary and pong handling.

Session.addHander() now links to that so you can get an unambiguous list.

I kept the @WebSocketMessage type list separate, which might not be the most readable for you, but I did organize it into text, binary, pong message handling, so that should be clearer for those readers who are thinking of it in those terms.

The threading issues are already captured in another one, so I'm going to close this one out.

Comment by dannycoward [ 04/Feb/13 ]

see last comment. I also made the specification document refer to the definition of parameters types and returns types on @WebSocketMessage instead of trying to maintain this in two places.

Comment by Pavel Bucek [ 05/Feb/13 ]

great, thanks!

Comment by stepan.kopriva [ 07/Feb/13 ]

According to the javadoc on @WebSocketMessage there can't be two methods in one class where one of the methods takes String as a parameter and the other one takes object parameter for which the endpoint has a text decoder.

The same holds for two methods where each takes different object parameter for which the endpoint has a text decoder.

Comment by dannycoward [ 08/Feb/13 ]

Yes, I think this was the big simplification what we decided in the expert group. But let me go back and double check.

Comment by dannycoward [ 20/Feb/13 ]

We have reconcluded that multiple message handlers won't work in generality. The basic problem is that there is no identifying data on an incoming message to tell you what kind of message it is, except string, binary or pong.

There is a potential (small) relaxation however, which is to allow one MessageHandler.Basic and one MessageHandler.Async per native message type: text and binary.

This can be mapped unambiguously, and might be moderately useful for some cases.

So I will propose this to the expert group.

Comment by dannycoward [ 26/Feb/13 ]

There is some resistance to relaxing the rules to allow one whole and one partial message handler per connection, in part because it is more complicated to specify and explain, and in part because it only has limited usefulness. So I'm closing this, we'll keep it as it is.





[WEBSOCKET_SPEC-100] Clarify semantics of EJB SSB and Singletons and CDI managed beans - as-websockets Created: 08/Jan/13  Updated: 01/Feb/13  Due: 31/Jan/13  Resolved: 01/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

as synopsis. Am working with Marnina to determine any other restrictions.



 Comments   
Comment by dannycoward [ 30/Jan/13 ]

What I think we have concluded is that we want websocket endpoints to be non-contextual managed beans. This is described in the Java EE spec (public draft, v7) EE 5.24.

In this case, other EE components can be injected into websocket endpoints. So the need for websocket endpoints to BE EJBs or managed beans themselves is greatly reduced: instead of using EJB/CDI services by being one, you can delegate to one very easily.

We may look at how to leverage the EJB model more directly in a future release.

Stateful session beans and singletons look like a good match with websocket endpoints, but:

  • we'd want singleton EJBs-as-websockets to be flagged Lock(LockType.READ) so that it recieved concurrent calls instead of getting them one-at-a-time from multiple clients.
  • we'd want some way to relax the restriction that websocket endpoint instances that were stateful session beans were removed whenever any of the methods threw a runtime exception.
Comment by dannycoward [ 01/Feb/13 ]

Websocket endpoints in Java EE containers can have things injected into them, just like the other web components like servlets, JSP beans etc





[WEBSOCKET_SPEC-99] Define lifecycle and cardinality of encoders and decoders. Created: 08/Jan/13  Updated: 26/Jan/13  Due: 25/Jan/13  Resolved: 26/Jan/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: dannycoward Assignee: Unassigned
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

as synopsis.



 Comments   
Comment by dannycoward [ 18/Jan/13 ]

New instance per connection per endpoint makes for a simple model.

This works for singleton endpoints and per connection endpoints equally well. No two threads in an encoder/decoder instance at any one time.

Will propose this to expert group.

Comment by dannycoward [ 26/Jan/13 ]

Fixed as proposed.





[WEBSOCKET_SPEC-98] Consider a property bag on EndpointConfiguration instead of subclassing for shared application state Created: 08/Jan/13  Updated: 16/Feb/13  Due: 08/Feb/13  Resolved: 16/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: New Feature Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v013

 Description   

As a simpler way to allow all instances of an endpoint to share some global state, use a property bag (EndpointConfiguration.get/setProperty(..)) instead of having to subclass EndpointConfiguration to do it. Avoids an extra developer class for the case where you just have object you want to share, rather than some other initialization code.



 Comments   
Comment by Pavel Bucek [ 08/Jan/13 ]

I'm using DefaultClientEndpointConfiguration class from tyrus (implements ClientEndpointConfiguration), which provides simple impl for all ClientEndpointConfiguration class; things would be even more messy if I wouldn't do that).

Current state:

    public static void current() throws URISyntaxException, DeploymentException {

        MyClientEndpointConfiguration cec = new MyClientEndpointConfiguration();
        cec.getProperties().put("MyKey", "MyValue");

        final WebSocketContainer client = ClientManager.createClient();
        client.connectToServer(MyEndpointCurrent.class, cec, new URI("ws://myUri"));
    }

    public static class MyEndpointCurrent extends Endpoint {
        @Override
        public void onOpen(Session session, EndpointConfiguration config) {
            if (config instanceof MyClientEndpointConfiguration) {
                MyClientEndpointConfiguration cec = (MyClientEndpointConfiguration) config;

                // voilà!
                final Object myProperty = cec.getProperties().get("MyKey");
            }
        }
    }

    public static class MyClientEndpointConfiguration extends DefaultClientEndpointConfiguration implements ClientEndpointConfiguration {
        private final Map<String, Object> properties = new HashMap<String, Object>();

        public MyClientEndpointConfiguration() {
            super(Collections.<Encoder>emptyList(), Collections.<Decoder>emptyList(), Collections.<String>emptyList(), Collections.<Extension>emptyList());
        }

        public Map<String, Object> getProperties() {
            return properties;
        }
    }

What might be more convenient for users:

    public static void wanna() throws URISyntaxException, DeploymentException {

        ClientEndpointConfiguration cec = new DefaultClientEndpointConfiguration.Builder().property("MyKey", "MyValue").build();

        final WebSocketContainer client = ClientManager.createClient();
        client.connectToServer(MyEndpointWanna.class, cec, new URI("ws://myUri"));
    }

    public static class MyEndpointWanna extends Endpoint {
        @Override
        public void onOpen(Session session, EndpointConfiguration config) {

            // voilà!
            final Object myProperty = config.getProperties().get("MyKey");
        }
    }

Last but not least - there is no way how can I utilize this in annotated endpoint case; this might be considered as another issue (please let me know, I can file it):

    public static void annotated() {
        MyClientEndpointConfiguration cec = new MyClientEndpointConfiguration();
        cec.getProperties().put("MyKey", "MyValue");

        final WebSocketContainer client = ClientManager.createClient();
        
        // ?? where should I put my ClientEndpointConfiguration instance?
        client.connectToServer(MyEndpoint.class, new URI("ws://myUri"));
    }
    
    @WebSocketClient
    public static class MyEndpoint {
        
        @WebSocketOpen
        public void onOpen(Session session, EndpointConfiguration config) {
            // ???
        }
    }
Comment by dannycoward [ 16/Feb/13 ]

We still need to be able to allow developer to attach arbitrary execution code to endpoint configs, but for sharing use data, the new config apis have included this.





[WEBSOCKET_SPEC-96] Allow Java primitives and boxed equivalents as message parameters to @WebSocketMessage methods Created: 07/Jan/13  Updated: 26/Jan/13  Due: 25/Jan/13  Resolved: 26/Jan/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

I think this can be unambiguously defined for incoming string messages. For each of the Java primitives, use the string constructor of the boxed equivalent using the incoming string parameter, and unbox it. For the boxed primitives, use the string constructor.

For binary messages, I don't think there's a standard way.



 Comments   
Comment by dannycoward [ 09/Jan/13 ]

will propose text message -> primitive/boxed equivalents decoders / i.e. should be able to have them as method parameters on @WebSocketMessage

Comment by dannycoward [ 26/Jan/13 ]

I have updated the spec and javadoc for this.





[WEBSOCKET_SPEC-95] Clarify @WebSocketOpen, @WebSocketClose, @WebSocketError can each only annotate one method per annotated endpoint Created: 07/Jan/13  Updated: 12/Feb/13  Resolved: 09/Jan/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Task Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

needs spelling out, otherwise, deployment error



 Comments   
Comment by dannycoward [ 09/Jan/13 ]

This is fixed in v012

Comment by stepan.kopriva [ 12/Feb/13 ]

Danny I have found this fix in the spec document, but it would be quite helpful for developers if this info is also in the javadoc on @WebSocketOpen, @WebSocketClose and @WebSocketError.





[WEBSOCKET_SPEC-94] WebSocketEndpoint.configuration should be an optional parameter Created: 07/Jan/13  Updated: 09/Jan/13  Resolved: 09/Jan/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

as synopsis



 Comments   
Comment by dannycoward [ 09/Jan/13 ]

This was an error, as the specification document indicated this was an optional parameter. Has now been fixed in the API repo.





[WEBSOCKET_SPEC-93] ServerEndpointConfiguration#getEndpointClass() for annotated endpoints Created: 07/Jan/13  Updated: 08/Feb/13  Due: 08/Feb/13  Resolved: 08/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: jitu Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

ServerEndpointConfiguration is used for both programmatic and annotated endpoints. What's the return value of this method for annotated endpoints ?



 Comments   
Comment by dannycoward [ 08/Feb/13 ]

although we may reshape some of these APIs, for version 12 this is clarified to be the class of the POJO.





[WEBSOCKET_SPEC-91] WebSocketOpen javadoc Created: 07/Jan/13  Updated: 09/Jan/13  Resolved: 09/Jan/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Pavel Bucek Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

please use

{@link }

syntax in javadoc.

additionally, you are referring to EndpointConfig class, which does not exist (it should probably be javax.websocket.EndpointConfiguration).



 Comments   
Comment by dannycoward [ 09/Jan/13 ]

Fixed, also in javadoc for the other annotations too.





[WEBSOCKET_SPEC-90] WebSocketContainer.connectoToServer Created: 04/Jan/13  Updated: 09/Jan/13  Resolved: 09/Jan/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Pavel Bucek Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified


 Description   

connectoToServer now takes only endpoint classes (this change was introduced in b11 - PR) instead of instances and there is no way how I can provide any configuration to that class.

Endpoint.onOpen has new parameter - EndpointConfiguration, but there are only methods to get encoders and decoders, no property bag. (Please note that I don't see any simple way how I can update Tyrus tests to new API without the possibility to configure my endpoints).



 Comments   
Comment by dannycoward [ 09/Jan/13 ]

Configurations can indeed be passed into the connectToServer methods: either explicitly as a parameter to the version of the method for programmatic endpoints, or in the annotations themselves in the case of the annotated endpoint version of the method.

I filed a separate RFE for the request to have a property bag on the endpoint configuration object.





[WEBSOCKET_SPEC-86] PongMessage typo and formatting Created: 03/Jan/13  Updated: 09/Jan/13  Resolved: 09/Jan/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: jitu Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

Here is a patch

Index: src/main/java/javax/websocket/PongMessage.java
===================================================================
— src/main/java/javax/websocket/PongMessage.java (revision 105)
+++ src/main/java/javax/websocket/PongMessage.java (working copy)
@@ -1,7 +1,7 @@
/*

  • DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
    *
  • * Copyright (c) 2012 Oracle and/or its affiliates. All rights reserved.
    + * Copyright (c) 2013 Oracle and/or its affiliates. All rights reserved.
    *
  • The contents of this file are subject to the terms of either the GNU
  • General Public License Version 2 only ("GPL") or the Common Development
    @@ -42,8 +42,9 @@
    import java.nio.ByteBuffer;

/**

  • * The PongMessage interface represents a web socket ping. PongMessages may be received by using
  • * a MessageHandler.Basic<PongMessage>. The payload of the PongMessage is the application data sent by the peer.
    + * The PongMessage interface represents a web socket pong. PongMessages may be
    + * received by using a {@code MessageHandler.Basic<PongMessage>}

    . The payload
    + * of the PongMessage is the application data sent by the peer.
    *

  • @author dannycoward
  • @since v008


 Comments   
Comment by dannycoward [ 09/Jan/13 ]

fixed.





[WEBSOCKET_SPEC-84] Typo WebSocketResponse#getHeaders() Created: 03/Jan/13  Updated: 09/Jan/13  Resolved: 09/Jan/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: jitu Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

/**

  • Return the list of Http Headers that came with the handshake request.
    *
  • @return the headers.
    */
    Map<String, List<String>> getHeaders();

Note "handshake request" instead of "handshake response" in the above javadoc

Also, the returned Map is modifiable and any changes to the map would be reflected in the handshake response headers. This is not clear from javadoc.

Will the returned Map would be empty or filled with headers the runtime is planning to send ?



 Comments   
Comment by dannycoward [ 09/Jan/13 ]

I have updated the javadoc to detail what the handshake response is.

The ClientEndpointConfiguration and ServerEndpointConfiguration interception methods clarify the semantics of what the HandshakeResponse objects represent at the two key points in the opening handshake interaction, and what can be inspected/modified when.





[WEBSOCKET_SPEC-85] Some DefaultClientConfiguration methods return ClientEndpointConfiguration Created: 03/Jan/13  Updated: 01/Feb/13  Due: 01/Feb/13  Resolved: 01/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: jitu Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

public ClientEndpointConfiguration setDecoders(List<Decoder> decoders) {

that should be

public DefaultClientConfiguration setDecoders(List<Decoder> decoders) {

Similarly, other methods setEncoders, setExtensions, setPreferredSubProtocols needs to be changed



 Comments   
Comment by Justin Lee [ 03/Jan/13 ]

My first question was, "why would you want to return a concrete class rather than the interface" but then noticed that those methods aren't on the interface at all. Why is that? Seems like an oversight.

Comment by jitu [ 03/Jan/13 ]

IMO, we shouldn't be adding the setter methods on the ClientEndpointConfiguration interface or its super interfaces. Container doesn't use these setter methods. Also, all the concrete impl will be forced to be mutable.

DefaultClientConfiguration is just one concrete impl that is using these setter methods to configure that information. Instead, it can use constructors, or a builder (if there are many parameters) to configure that information.

Comment by dannycoward [ 01/Feb/13 ]

This is an oversight. Its trying to use the builder pattern to set up the information. So the returns should be DefaultClientConfiguration.

Comment by dannycoward [ 01/Feb/13 ]

fixed as suggested.





[WEBSOCKET_SPEC-83] Define the portability semantics of ContainerProvider Created: 03/Jan/13  Updated: 08/Feb/13  Due: 05/Feb/13  Resolved: 08/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: jitu Assignee: dannycoward
Resolution: Fixed Votes: 1
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

Spec needs to define the portability semantics of ContainerProvider API. At present, it is using a private and undocumented system property to load a provider in the RI's API. If this is the way a provider needs to be located (instead of much preferred ServiceLoader mechanism), this needs to be documented. Note that using a system property doesn't work for a web application that wants use a custom provider(by bundling the provider in a war file).

Also, API's system property "websocket.clientcontainer.classname" is arbitrary. Usually, it is the class name in many other API, i.e "javax.websocket.ContainerProvider" in this case. WebSocketContainer class name for client container is also misleading.



 Comments   
Comment by Pavel Bucek [ 10/Jan/13 ]

ContainerProvider (as it is now) is basically unusable. Jitu covered it pretty well;

better implmentation might look like ContainerProvider in Tyrus: http://java.net/projects/tyrus/sources/source-code-repository/content/trunk/core/src/main/java/org/glassfish/tyrus/javax/websocket/ContainerProvider.java?rev=275

Comment by dannycoward [ 25/Jan/13 ]

Yes I agree using the service loader would be a lot better.

But the API class should not be looking for a Tyrus class as the default if no other can be found. If no provider implementation is configured, then there will be no provider.

Thoughts ?

Comment by Pavel Bucek [ 25/Jan/13 ]

ServiceLoader can look for implementation of certain interface, it does not need to depend on that particular implementation.

So.. you can look for javax.websocket.WebSocketContainer and if you have jar file with META-INF/services/javax.websocket.WebSocketContainer file with single line containing fully qualified name of your implementation of WebSocketContainer, it will be returned. See http://docs.oracle.com/javase/7/docs/api/java/util/ServiceLoader.html for more details.

Comment by dannycoward [ 25/Jan/13 ]

Yeah I know that. The example you posted looks for a particular Tyrus class if none is found from the service loader is what I was concerned about....

Comment by dannycoward [ 08/Feb/13 ]

This has been updated to use the ServiceLoader.





[WEBSOCKET_SPEC-147] @WebSocketClose: javadoc not in sync with the Java API Web Socket pdf document Created: 21/Feb/13  Updated: 21/Feb/13  Resolved: 21/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: 1.0
Fix Version/s: None

Type: Bug Priority: Major
Reporter: mikc22 Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v013

 Description   

The javadoc says:

The method may only take the following parameters:-

optional Session parameter
optional CloseReason parameter
Zero to n String parameters annotated with the WebSocketPathParam annotation.

The pdf says:
The the decorated method can only have optional Session parameter and zero to n String parameters. Which looks like the CloseReason is lost here.



 Comments   
Comment by dannycoward [ 21/Feb/13 ]

Thanks for catching this. The javadoc is correct, and the spec document is updated in v013.





[WEBSOCKET_SPEC-145] Rename HandshakeRequest.getSession -> getHttpSession Created: 20/Feb/13  Updated: 22/Feb/13  Resolved: 22/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: arungupta Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v013

 Description   

javax.websocket.server.HandshakeRequest#getSession() should be called getHttpSession().



 Comments   
Comment by dannycoward [ 22/Feb/13 ]

yes it should ! fixed in v013.





[WEBSOCKET_SPEC-144] Discrepancy between URIs of programmatic and annotated endpoint Created: 17/Feb/13  Updated: 21/Feb/13  Resolved: 21/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: arungupta Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v013

 Description   

There is a discrepancy between programmatic and annotated endpoint. The following two code work in GlassFish b76:

@WebSocketEndpoint(value="/websocket")
public class MyEndpoint {

AND

public class MyServerConfiguration extends DefaultServerConfiguration implements ServerEndpointConfiguration {

public MyServerConfiguration()

{ super(MyEndpoint.class, "websocket"); }

But annotated endpoint takes the URI as "/websocket" and the programmatic endpoint takes the URI as "websocket".

The spec requires annotated endpoint URI to start with / but could not find any such requirement in programmatic endpoint.



 Comments   
Comment by dannycoward [ 21/Feb/13 ]

yes I agree the programmatic config should require the leading / consistent with the annotation. So this is updated in v013 of the spec.





[WEBSOCKET_SPEC-143] ContainerProvider javadoc need to update the location of service provider Created: 17/Feb/13  Updated: 22/Feb/13  Resolved: 22/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: arungupta Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v013

 Description   

ContainerProvider javadoc says:

Specifically, the fully qualified classname of the container implementation of ContainerProvider must be listed in the META-INF/services/javax.websocket.ContainerProvider file in the JAR file containing the websocket API.

But I see this file in:

unzip -p tyrus-client.jar META-INF/services/javax.websocket.ContainerProvider
org.glassfish.tyrus.client.ClientManager

The javadoc needs to be fixed as this will be an implementation-specific class.



 Comments   
Comment by dannycoward [ 21/Feb/13 ]

Hey Arun,

If I understand what you're saying, this is actually how its supposed to work...

Inserting the container specific classname into the META-INF/services/javax.websocket.ContainerProvider file is the means by which the API classes bootstrap the entry point for the implementation.

So if the API JAR is bundled with tyrus, you would expect some tyrus specific classname in that file.

If the API JAR is bundled with Jetty, you'd expect some Jetty specific classname here.

This is how the JDK ServiceLoader mechanism used underneath ContainerProvider.getWebSocketContainer() allows the API JAR to be configured without having to recompile anything.

Does that explain it ?

Comment by arungupta [ 22/Feb/13 ]

The javadoc says it should be bundled in the API jar file but its bundled in the implementation class. So either javadoc needs to be fixed or the file needs to be bundled in the API jar file.

Comment by dannycoward [ 22/Feb/13 ]

ok got it. The javadoc's been updated: it should be in the implementation jar.





[WEBSOCKET_SPEC-142] Remove Session#getId() Created: 16/Feb/13  Updated: 26/Feb/13  Resolved: 26/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: markt_asf Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v014

 Description   

I'm unclear what use case this method is intended to support. Once obtained it can't be used for anything and it isn't a concept that exists within the WebSocket spec.

Can it be removed?



 Comments   
Comment by dannycoward [ 26/Feb/13 ]

We'll keep this in for loggin/debugging/tracking purposes.





[WEBSOCKET_SPEC-141] websockets api: how to pass instance to ServerEndPointConfiguration ? Created: 14/Feb/13  Updated: 16/Feb/13  Resolved: 16/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: mikc22 Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v013

 Description   

I want to pass some custom objects to the EndPoint running on the server. In the past it was possible to use a HashMap<String, Object> in ServerEndpointConfiguration object where it was possible to pass custom parameters. Currently I solved it like this:

public class ProgrammaticServerConfiguration implements ServerEndpointConfiguration {

private static ConcurrentMap<String, BasicTextMessageHandler> _messageHandlers = new ConcurrentHashMap<String, BasicTextMessageHandler>();

public static void registerMessageHandler(String name, BasicTextMessageHandler handler)

{ _messageHandlers.put(name, handler); }

public static BasicTextMessageHandler getMessageHandler(String name)

{ return _messageHandlers.get(name); }

...

}

However it would be useful if one can pass an instance of ServerConfigurationEndpoint similarly as it is possible for the ClientConfigurationEndpoint:

Session clientSession = wsc.connectToServer(
ProgrammaticClient.class,
new ProgrammaticClientConfiguration(
new BasicTextMessageHandlerClient()),
testConf.getURI());



 Comments   
Comment by dannycoward [ 16/Feb/13 ]

Now there is a property bag on EndpointConfig in v013, so I am closing this one out.

/**

  • This method returns a modifiable Map that the developer may use to store application
  • specific information relating to the endpoint that uses this
  • configuration instance. Web socket applications running on distributed
  • implementations of the web container should make any application
  • specific objects stored here java.io.Serializable, or the object may
  • not be recreated after a failover.
    *
  • @return a modifiable Map of application data.
    */
    Map<String, Object> getUserProperties();




[WEBSOCKET_SPEC-140] Clarify relationship between WebSocketContainer#setMaxSessionIdleTimeout() and Session#setTimeout() Created: 13/Feb/13  Updated: 16/Feb/13  Resolved: 16/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: markt_asf Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v013

 Description   

It isn't clear from the Javadoc what the relationship is between these two. I see two options:

1. WebSocketContainer#setMaxSessionIdleTimeout() sets the default for Session#setTimeout()

2. WebSocketContainer#setMaxSessionIdleTimeout() sets the maximum permitted timeout and Session#setTimeout() may not exceed this.

My guess is that the intended behaviour is 1 to align with how max buffer size is handled. Maybe make the method name setDefaultSessionIdleTimeout() ?

On a related note are zero or negative input values allowed for WebSocketContainer#setMaxSessionIdleTimeout() and if so, what do they mean? My guess is the same as for Session#setTimeout().



 Comments   
Comment by dannycoward [ 13/Feb/13 ]

It was supposed to be 1.

how about option1, and naming: Session#set/getMaxIdleTimeout to be consistent with WebSocketContainer#set/getDefaultMaxSessionIdleTimeout()

And yes the non-positive was supposed to mean that.

Let me raise this fix on the list.

Comment by dannycoward [ 16/Feb/13 ]

proposed without objection, so fixed as proposed.





[WEBSOCKET_SPEC-138] websockets api javadoc: include message handler registration for onOpen method Created: 13/Feb/13  Updated: 14/Feb/13  Resolved: 14/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: mikc22 Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v013

 Description   

1) I think it would be useful to have an example for typical onOpen() usage:

Example:
@Override
public void onOpen(Session s) {
final RemoteEndpoint remote = session.getRemote();
s.addMessageHandler(new MessageHandler.Basic<String>() {
public void onMessage(String text) {
try

{ remote.sendString("Pong from server:"+text); }

catch(Exception ex)

{ ... }

}
}
}

2) I think it should be useful to link this example in Session.addMessageHandler, and in MessageHandler.*.onMessage() sections
3) Since onMessage() is of type void it would be useful to have an example where the RemoteEndpoint obtained, like in 1)



 Comments   
Comment by dannycoward [ 14/Feb/13 ]

good idea !

I put in the example and links, will show up in the build with v013 api in the next couple weeks.





[WEBSOCKET_SPEC-139]  getNegotiatedSubprotocol(): not sure if we can return null Created: 13/Feb/13  Updated: 14/Feb/13  Resolved: 14/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: mikc22 Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v013

 Description   

The documentation says:
"
Return the subprotocol this server endpoint has chosen from the requested list supplied by a client who wishes to connect, or none if there wasn't one this server endpoint liked. See Sending the Server's Opening Handshake

Parameters:
requestedSubprotocols - the requested subprotocols.
Returns:
the negotiated subprotocol.
"
Does it mean we can return a null String or "" empty String ?



 Comments   
Comment by dannycoward [ 14/Feb/13 ]

I've clarified this both on session and the ServerEndpointConfiguration and DefaultServerCOnfiguration to be the empty string





[WEBSOCKET_SPEC-135] Improve modularity around client/server split Created: 11/Feb/13  Updated: 28/Feb/13  Resolved: 28/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: rstoyanchev Assignee: jitu
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v014

 Description   

As of draft 12 there are two jars named "javax.websocket-api" (aka server) and "javax.websocket-client-api". As in draft 11 there is a server sub-package with all other classes (common and client) being in the top level package. I understand most implementations are expected to implement client and server API, while it's also possible for a library to implement client side only. However, things look pretty confusing to someone not familiar with that implicit expectation.

Given "javax.websocket-client-api", one would expect "javax.websocket-server-api" with shared functionality in "-common" or "-core". This does mean one extra module but that makes more sense from an application perspective at runtime. If I'm writing a server-only application I need to depend on server and common whereas currently I'd have to depend on server and client with client being included only because I need the common (and not the client) classes.

Similarly it would greatly help in understanding the API if there was a client package just like there is a server package. It's very easy to recognize the 6 server-specific classes but the top level package contains 25 classes and it's not easy to make out which ones are shared and which ones are client specific. To look at it from another perspective, if there is a server package why shouldn't there be a client package?



 Comments   
Comment by rstoyanchev [ 12/Feb/13 ]

I see now that `mvn install` bundles all classes in "javax.websocket-api", which means I should be able to get all classes from it. However, the .pom still shows a transitive dependency on "javax-.websocket-client-api", which means I'll end up with two jars, unless I explicitly exclude "javax-.websocket-client-api". Is this an error? Also the "javax.websocket-api" sources jar contains only server classes, which is inconsistent.

Comment by jitu [ 13/Feb/13 ]

I am aware that the javax.websocket-api-sources.jar needs to fixed.

But isn't it ok for javax.websocket-api.jar to have a dependency on javax.websocket-client-api.jar ? Where are you facing the problem with two jars ?

Comment by rstoyanchev [ 13/Feb/13 ]

But isn't it ok for javax.websocket-api.jar to have a dependency on javax.websocket-client-api.jar ?

It's confusing if nothing else but it could potentially lead to issues in the future when there is more than one version of the websocket api.

Comment by dannycoward [ 15/Feb/13 ]

The split we want here is that we have two profiles

one that runs on web servers
one that runs on desktop machines

The client/server terminology is explained in the spec document, but a websocket client is one that only initiates connections, a websocket server is one that accepts connections.

The first profile needs to do both (the expert group wants websockets on a web server to be able to accept connections and initiate them). The second profile only needs to have 'client' functionality (the expert group wanted the desktop profile to initiate connections but not accept them). If only the web server didn't have 'client' functionality it would all be easier !

The javax.websocket package is everything in common to both profiles. The javax.websocket.server package is everything that only applies to websockets in web servers.

So we have the right split of packages/classes for the two profiles. We will always version them the same, and release updates simultaneously.

Would it help to call the JAR files something different ? javax.websocket-web and javax.websocket-client ?

Danny

Comment by rstoyanchev [ 27/Feb/13 ]

Sorry for not responding sooner. I think the names are fine. It looks like the intent for javax.websocket-api is to contain all necessary files for both client and server but its pom indicates a dependency on javax.websocket-client, which technically is not needed since javax.websocket-api already contains all the files. This arrangement is a bit odd but not a show stopper. Feel free to close this issue.

Comment by dannycoward [ 28/Feb/13 ]

OK thanks Rossen for taking a close look here. Closing this one out.





[WEBSOCKET_SPEC-132] RemoteEndpoint#setBatchingAllowed(boolean) should throw IOException Created: 11/Feb/13  Updated: 12/Feb/13  Resolved: 12/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: markt_asf Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v013

 Description   

Calling this method to disable batching when there are unsent messages requires that the messages be sent. An IOException may occur when sending messages so this method needs to throw IOException.



 Comments   
Comment by dannycoward [ 12/Feb/13 ]

Thanks for catching this Mark. I've updated the API and javadoc with the IOException in this case.





[WEBSOCKET_SPEC-133] DefaultServerConfiguration#getEndpointClass() should return Class<? extends Endpoint> Created: 11/Feb/13  Updated: 16/Feb/13  Resolved: 16/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: markt_asf Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v013

 Description   

When the endpoint class is set, the parameter passed to the constructor is of type:
Class<? extends Endpoint>

Therefore, getEndpointClass() should return the same type.



 Comments   
Comment by dannycoward [ 11/Feb/13 ]

We also have annotated endpoints to deal with here - in which the endpoint class is the class of the POJO which could be anything.

When I send out the proposed reshaping of the config APIs I think this should become clearer.

Comment by markt_asf [ 12/Feb/13 ]

Ah. I wasn't thinking about POJOs. In which case, the constructor for DefaultServerConfiguration needs to be changed.

Happy to wait to see the new config APIs before progressing this.

Comment by dannycoward [ 12/Feb/13 ]

ok. now you can look at the new apis - I think they tighten things up considerably - do take a look when you get chance !

Comment by dannycoward [ 16/Feb/13 ]

This is definately fixed in the cleaned up APIs, so I am closing this one out.





[WEBSOCKET_SPEC-157] Typo in ServerEndpointConfigurationBuilder javadocs Created: 28/Feb/13  Updated: 28/Feb/13  Resolved: 28/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: arungupta Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v014

 Description   

v013 javadocs for ServerEndpointConfigurationBuilder says:

The ServerEndpointConfigurationBuilder is a class used for creating ServerEndpointConfigurationBuilder objects for the purposes of deploying a client endpoint.

Change "client endpoint" to "server endpoint".



 Comments   
Comment by dannycoward [ 28/Feb/13 ]

whoops ! thanks for reporting





[WEBSOCKET_SPEC-153] @OnClose and Endpoint.onClose() differences Created: 25/Feb/13  Updated: 01/Mar/13  Resolved: 01/Mar/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Pavel Bucek Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v014

 Description   

@OnClose and Endpoint.onClose() javadoc mention session "state", one as already closed and the other one as "about to close". This needs to be unified.



 Comments   
Comment by dannycoward [ 01/Mar/13 ]

The javadoc for Session.close and onClose and @OnClose has been updated to addresss this and related close semantics.





[WEBSOCKET_SPEC-152] Final fields in SendResult Created: 23/Feb/13  Updated: 26/Feb/13  Resolved: 26/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: jitu Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v014

 Description   

public class SendResult {

  • private Throwable exception;
  • private boolean isOK = true;
    + private final Throwable exception;
    + private final boolean isOK;

and corresponding changes in the constructors



 Comments   
Comment by dannycoward [ 26/Feb/13 ]

done.





[WEBSOCKET_SPEC-131] Consider merging RemoteEndpoint and Session Created: 06/Feb/13  Updated: 22/Feb/13  Resolved: 22/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Pavel Bucek Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v013

 Description   

RemoteEndpoint is not used anywhere else that in Session class and since exactly one RemoteEndpoint is always connected to exactly one Session, having these two separated might seem as unnecessary redundancy.



 Comments   
Comment by dannycoward [ 22/Feb/13 ]

Particularly with the new refactoring, this makes less sense now than it did before.

Also No-one spoke up in defense of it in the eg when I raised it so I'm closing it out.





[WEBSOCKET_SPEC-130] Wrong javadoc for @WebSocketMessage return type Created: 04/Feb/13  Updated: 04/Feb/13  Resolved: 04/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: stepan.kopriva Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

The javadoc for @WebSocketMessage says that return type (except others) may be anything for which there is a decoder. This should be changed to anything for which there is an encoder.



 Comments   
Comment by dannycoward [ 04/Feb/13 ]

thanks ! fixed.





[WEBSOCKET_SPEC-128] DefaultServerConfiguration - methods implementation - b12 Created: 01/Feb/13  Updated: 16/Feb/13  Resolved: 16/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Pavel Bucek Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v013

 Description   

methods to implement:

checkOrigin
getNegotiatedExtensions
getNegotiatedSubprotocol



 Comments   
Comment by dannycoward [ 06/Feb/13 ]

we're exploring a way for the implementation, not the API to support these.

Comment by dannycoward [ 16/Feb/13 ]

in the new API these have to be implemented in the container so I am closing this one out !





[WEBSOCKET_SPEC-69]  Publish same programmatic endpoint type to many different paths Created: 09/Dec/12  Updated: 16/Feb/13  Due: 08/Feb/13  Resolved: 16/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: jmarine Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Related
is related to WEBSOCKET_SPEC-114 Programmatic deployment of server end... Resolved
is related to WEBSOCKET_SPEC-116 WebSocketContainer.connectToServer ea... Resolved
Tags: v013

 Description   

I think the "publishServer" method parameter in ServerContainer class should be modified:
instead of receiving a "class" (that was needed in revision 49 to create an endpoint instance per peer), wouldn't it be more useful now to receive a ServerEndpointConfiguration instance object?

i.e:

Supposing it had the following method's signature:

void publishServer(ServerEndpointConfiguration config)
throws DeploymentException;

Then, it could be possible to register the same endpoint type with many different configurations.

i.e:

theServerContainer.publishServer(new MyChatRoomServerEndpointConfiguration("/room1"));

theServerContainer.publishServer(new MyChatRoomServerEndpointConfiguration("/room2"));



 Comments   
Comment by dannycoward [ 16/Feb/13 ]

The updated ServerApplicationConfiguration and cleaned up configuration APIs in v013 allow
the same config class to be instantiated with different properties and used to deploy
the same endpoint class in various different configured states (including to multiple paths).

There is a separate RFE files for programmatic deployment, so I am closing this one out.





[WEBSOCKET_SPEC-178] Typo and missing javadoc in ServerEndpoint.Configurator.modifyHandshake Created: 03/Apr/13  Updated: 22/Apr/13  Resolved: 22/Apr/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: 1.0

Type: Bug Priority: Major
Reporter: arungupta Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: final

 Description   

ServerEndpoint.Configurator.modifyHandshake has a typo:

"has already has already checked" -> "has already checked"

Also, there no javadoc for ServerEndpointConfig parameter.



 Comments   
Comment by dannycoward [ 22/Apr/13 ]

This is now fixed in final





[WEBSOCKET_SPEC-127] Consider removing setBufferSize() on containers Created: 30/Jan/13  Updated: 03/Feb/13  Due: 05/Feb/13  Resolved: 03/Feb/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Improvement Priority: Major
Reporter: dannycoward Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v012

 Description   

so it doesn't need to be checked all the time



 Comments   
Comment by markt_asf [ 31/Jan/13 ]

Some related issues:

1. Session has one limit for text and binary messages whereas WebSocketContainer has separate limits. Need to be consistent.

2. The method names should be consistent between Session and WebSocketContainer (unless of course they are meant to be completely different concepts in which case much more explantion in the Javadoc is required).

3. Make clear if the limits are for incoming, outgoing or both. The assumption from the EG list is incoming only.

4. Why allow limits greater than Integer.MAX_VALUE when that is the largest message / partial message Java is able to deliver?

Comment by dannycoward [ 02/Feb/13 ]

So I'm proposing:-

1. separate text/binary limits on session to make it consistent with WebSOcketContainer.
2. Put Default in the WebSocketContainer method names + javadoc to disambiguate all session/session override.
3. Clarify limits for incoming only. Explore outgoing buffer size control in .next.
4. Make limits ints.

Comment by dannycoward [ 03/Feb/13 ]

resolved as proposed.





[WEBSOCKET_SPEC-159] Encoder/Decoder#setEndpointConfig Created: 04/Mar/13  Updated: 06/Mar/13  Resolved: 06/Mar/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Pavel Bucek Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Dependency
blocks TYRUS-122 Implement Encoder/Decoder#init(Endpoi... Resolved
Tags: proposedfinaldraft

 Description   
    /**
     * This method is called with the endpoint configuration object of the
     * endpoint this decoder is intended for when
     * it is about to be brought into service, and with {@code null} when
     * the implementation has finished using it.
     *
     * @param config the endpoint configuration object if being brought into use
     * or {@code null} if being taken out of use.
     */
    void setEndpointConfig(EndpointConfig config);

please rename to something else(/or adjust documentation). This is not "setter", this is lifecycle controller.

Additionally, consider changing Encoder/Decoder to abstract class which has setEndpointConfig implemented, because it is not needed for majority of implementations (educated guess).



 Comments   
Comment by dannycoward [ 06/Mar/13 ]

The APi has been renamed to follow the init()/destroy() pattern of the servlet api.

Encoder and Decoder now have Adapter implementations as a convenience for developers who don't need to do anything with the lifecycle methods.





[WEBSOCKET_SPEC-158] HandshakeRequest documentation Created: 01/Mar/13  Updated: 01/Mar/13  Resolved: 01/Mar/13

Status: Resolved
Project: websocket-spec
Component/s: None
Affects Version/s: None
Fix Version/s: None

Type: Bug Priority: Major
Reporter: Pavel Bucek Assignee: dannycoward
Resolution: Fixed Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Tags: v014

 Description   
  • use {@code null}

    in javadoc (instead of plain null) - applies most likely to more than this class

    /**
     * Return a reference to the HttpSession that the web socket handshake that started this
     * conversation was part of, if applicable.
     *
     * @return the http session.
     */
    Object getHttpSession();

does not define what should be returned if "not applicable".

    /**
     * Return the query string associated with the request.
     *
     * @return the query string≥
     */
    String getQueryString();

typo "≥"

    /**
     * Checks whether the current user is in the given role.
     *
     * @param role the role being checked
     * @return whether the user is in the role
     */
    boolean isUserInRole(String role);

needs to specify where the role should be taken and what to do if not in authenticated state (as in "getUserPrincipal").



 Comments   
Comment by