Tuesday Jul 02, 2013

Tyrus 1.1

It might seem like there is not much time passed since Tyrus 1.0 (Java API for WebSocket reference implementation) release, but the fact is it was frozen several weeks before going public and development in the trunk continued. Tyrus 1.1 brings some new features and improvements:

  • client-side proxy support
  • simple command line client
  • various stability/performance fixes (see below for complete list)

Individual blog posts about highlighted features will follow, same as related user guide chapters.. stay tuned!

Tyrus 1.1 is already integrated in Glassfish trunk - you can download nightly build or upgrade to newer Tyrus manually (replace all Tyrus jars; I know this is not very user friendly, so I'll try to come up with some better solution or at least simple guide).

Complete list of bugfixes/improvements:

Related links:

Wednesday Jun 19, 2013

Tyrus 1.0

Hi all,

Java EE 7 was released last week and lots of new exciting libraries and frameworks with it. One of them is Tyrus 1.0, reference implementation of JSR-356: Java API for WebSocket.

Tyrus has new home page (thanks to whole Grizzly team to allow us use their web as a base for ours), user guide and much more. Please check it out on https://tyrus.java.net and let us know what you think on users@tyrus.java.net. We are always open for any suggestions or requests (features, tutorials, documentation, ...)!

Tyrus project has bigger ambition than just be reference implementation, so stay tuned, some cool features are planned (and already done) for Tyrus 1.1 release. If you have anything you would want to get into it, please file a bug/improvement on our issue tracker.


Friday Jun 07, 2013

Tyrus 1.0 user guide

We published first version of Tyrus user guide (thanks Stepan!) and we are looking for any feedback. I'm pretty sure current version would be sufficient for most of usecases, but there is always room for improvements.

 User guide:

Feel free to drop us a note about anything you'd expect to find there to users@tyrus.java.net. Thanks!

Tuesday Apr 02, 2013

Tyrus 1.0-rc1 released

Glassfish HCF is almost here, so is another Tyrus release. This one should be feature complete – that means all features and usecases described in the WebSocket specification (JSR 356) should work. We’ll see how many bugs will be raised after release..

Anyway, new WebSocket API (1.0-rc3) was released in the meantime, so there are some changes which might affect existing applications written using Tyrus/WebSocket API.

So let’s start:

  • ServerContainerProvider is gone.
  • ServerEndpointConfig.Configurator#matchesURI is gone
  • Encoder/Decoder.Adapter is gone.

And that’s basically it. There are additional changes in the spec document, mostly related to wording and some corner cases, but there is one thing which I want to point out – WebSocket spec 1.o-rc3 introduces path matching algorithm. See the spec itself for detailed description, but short summary would be: we got rid of customizable URI matching and replaced it with “standard” one, which still allows path templates and solves issue with multiple templates matching to same path. Additionally, RI (Tyrus) should not allow to deploy two endpoints with exactly same path templates (in terms of parsed state, so.. “/foo/bar” and “/foo/{bar}” are different, but “/foo/{bar}” and “/foo/{baz}” are the same).

Tyrus already implements it, so you can checkout latest Glassfish and try it out or wait for b83.

Other changes in Tyrus itself were mainly about getting done spec features and some bugfixing (of course). Latest and more interrestion additions are session timeouts and buffer size implementations. Also we managed to resolve threading issues on linux, so if you have experienced them, please try recent Glassfish and let us know if you still see any issue.

I hope that covers all bigger changes, but this post is not supposed to be complete list; if you want to see them all, please check API javadoc and spec document. And as always, you can always ask us! Tyrus (implementation): users@tyrus.java.net ; API: users@websocket-spec.java.net.

Saturday Mar 09, 2013

Tyrus 1.0-b13 released

Tyrus 1.0-b13 is out and it brings new WebSocket API 1.0-rc1, which contains some bigger renames and additions, like the last time. Since it is going to affect almost all code written using previous API, I'll again try to summarize changes to make transition as easy as possible.


Original New
EndpointConfiguration EndpointConfig
ServerEndpointConfiguration ServerEndpointConfig
ClientEndpointConfiguration ClientEndpointConfig
ServerEndpointConfigurator ServerEndpointConfig.Configurator
ClientEndpointConfigurator ClientEndpointConfig.Configurator
ServerApplicationConfiguration ServerApplicationConfig
ServerEndpointConfigurationBuilder ServerEndpointConfig.Builder
ClientEndpointConfigurationBuilder ClientEndpointConfig.Builder
MessageHandler.Basic MessageHandler.Whole
MessageHandler.Async MessageHandler.Partial

New Features

Encoder and Decoder interface got two new methods - init(EndpointConfig) and destroy(). As you most likely guessed out already, init is called when Encoder/Decoder is initiated and destroy when it is going to be destroyed or no longer used. Lifecycle of these objects changed from singleton to per session. Additionally Encoder.Adapter and Decoder.Adapter were added with empty impl of mentioned methods to ease implementing custom coders which do not rely on newly added methods.

ServerContainer and ServerContainerProvider have been introduced, but there is still open discussion about functionality they should provide, so some changes might happen here. ServerContainer allows users to "dynamically" add some endpoints during deployment, but its functionality is limited only to Servlet deployment phase. See javadoc for more information or check out test on Tyrus workspace - tests/servlet/dynamic-deploy or download from maven central - dynamic-deploy sample.

WebSocketContainer connectToServer(...) methods which take endpoint instance are back, enjoy ;)

EndpointConfig now has getters for sets of Encoder/Decoder classes instead of instances (it relies to scope change mentioned in 3 paragraphs above). It also nicely matches annotated case (see @ServerEndpoint and @ClientEndpoint).

ServerEndpointConfig.Configurator (used to be ServerEndpointConfigurator) has one new method getEndpointInstance(Class<T> clazz), which can be overridden and will be used to create new instances of all endpoints. So you can easily influence scoping of created instances. But beware, you won't be able to do anything more granular than one endpoint instance per session. Container provided implementation should support EJB and CDI, check out our CDI sample.

I hope that covers all bigger changes, other things are minor modifications mostly, like changing thrown exceptions etc. This short post is not supposed to be complete list of changes, if you want to see them all, please check API is javadoc and spec document: http://java.net/projects/websocket-spec/downloads/directory/Spec%20javadoc%20Drafts/Proposed%20Final%20Draft . And as always, you can always ask us! Tyrus (implementation): users@tyrus.java.net ; API: users@websocket-spec.java.net.

Wednesday Feb 27, 2013

Tyrus 1.0-b12 released

This release implements new version of WebSocket API which introduces major renames and even some changes in the way how you can configure advanced behavior. Unfortunately, this will make all related applications written using Tyrus uncompilable and already compiled ones undeployable (when integrated to Glassfish).

I'm sure we will receive lots of bugs relates to this change, but all I can do is try to prevent is somehow - for example by writing list of changes which you are reading right now :).

Important renames

Original name Current name
@WebSocketEndpoint @ServerEndpoint
@WebSocketClient @ClientEndpoint
@WebSocketOpen @OnOpen
@WebSocketMessage @OnMessage
@WebSocketPathParam @PathParam
@WebSocketClose @OnClose
@WebSocketError @OnError

There were no changes in packaging, so javax.websocket or javax.websocket.server is still valid.

Other changes

Another set of changes is related to Endpoint configuration. ServerEndpointConfiguration and ClientEndpointConfiguration is still there, but default implementations are gone (package private); users are supposed to use ServerEndpointConfiguraiontBuilder and ClientEndpointConfigurationBuilder in order to create new configuration instance. This change is not yet complete, so prepare for another renaming (Configuration will be Config).

Last but not least is separating user implementation from Configuration to Configurator. There are two of them, Server and Client side and they take care of calls like "matchURI", "modifyHandshake", "beforeRequest", "afterResponse". Usually you don't really need to call them, so API/RI providers default implemetation, but you might find these useful in some advanced cases, like implementing your own totally cool and unheard path matching algorithm. This class will also be renamed in next release (to something like ServerEndpointConfig.Configurator), but functionality should stay very similar (if not exactly the same).

Additionall, @ServerEndpoint and @ClientEndpoint now do NOT have configuration parameter. Everything from EndpointConfiguration should be configurable as annotation parameters plus you can set Configurator here for some more advanced usecases.

Deployment has been also altered. ServerApplicationConfiguration now deploys annotated classes or ServerEndpointConfiguration INSTANCES. Newly introduced method "getEndpointConfigurations" takes set of scanned Endpoint descendants and its up to implementor which of them will be included in returned set. Endpoint descendant needs some more info about the deployment (path, encoders, decoders, ...), so ServerEndpointConfiguration has to be created. Please note that any "loadable" endpoint can be returned (scanned classes may be ignored).

Session interface also received some refactorings, "getRemote()" dissapeared and was replaced by "getBasicRemote()" and "getAsyncRemote()". You can guess what can you do with them. On a related note - RemoteEndpoint is no longer usable on its own, it just provides common base for RemoteEndpoint.Basic and RemoteEndpoint.Async. Methods related to sending messages were also renamed, sendString is now sendTest, sendBytes is now sendBinary and these names are used for partial messages as well (only difference is now different parameters).

Let's get to the code part:

Plain echo endpoint:

public class PlainEcho {

    public String onMessage(String s) {
        return s;


    @ServerEndpoint(value = "/echo", configurator = MyServerConfigurator.class)
    public static class TestEndpoint {

        public String onMessage(String message) {
            return message;

    public static class MyServerConfigurator extends ServerEndpointConfigurator {

        public void modifyHandshake(ServerEndpointConfiguration sec,
                                    HandshakeRequest request,
                                    HandshakeResponse response) {
            final List<String> list = request.getHeaders().get(HEADER_NAME);
            response.getHeaders().put(HEADER_NAME, list);

ServerApplicationConfiguration programmatic deployment:

    public static class MyAppConfig implements ServerApplicationConfiguration {

        public Set<ServerEndpointConfiguration> getEndpointConfigurations(Set<Class<? extends Endpoint>> endpointClasses) {
            return new HashSet<ServerEndpointConfiguration>() {{
                add(ServerEndpointConfigurationBuilder.create(MyEndpoint.class, "/myEndpoint").build());


        public Set<Class<?>> getAnnotatedEndpointClasses(Set<Class<?>> scanned) {
            return null;


    public void onOpen(Session session) throws IOException {
        final Future<Void> future = session.getAsyncRemote().sendText("myText");

I'm sure I did not covered all changes (things are still moving forward); best source for info about API is javadoc and spec document: http://java.net/projects/websocket-spec/downloads/directory/Spec%20javadoc%20Drafts/v013 . And as always, you can always ask us! Tyrus (implementation): users@tyrus.java.net ; API: users@websocket-spec.java.net.

Friday Jan 18, 2013

Tyrus 1.0-b09 released

I've started working on new project - Reference Implementation of JSR 356: Java API for WebSocket - Tyrus and we just released new version.

What is Tyrus?

Tyrus providers implementation for JSR 356 plus some other (currently minor) improvements. Project itself is still in development phase, so you probably don't want to use it in production environment - especially when specification itself is not yet final - but if you want to be on track with this project, this is the release you want to use. We have worked hard to get implementation to support most of JSR-356 features and hopefully all core functionality.

Our implementation passes most of Autobahn testsuite (there are some Servlet 3.1 related issues but also in our implementation, I don't want to blame only Servlet folks ;) ). We should sort that out in next release cycle.

How can I try it?

Best way would be with fresh Glassfish, which should contain Tyrus 1.0-b09 (it is not available yet, but should be later today; link). Then you can build Echo sample from Tyrus samples directory and start exploring WebSockets and create simple game or other application which can take advantage of bi-directional communication provided by WebSocket protocol.

How to run Echo sample:

if you really want just quick peek, you can download Tyrus echo sample war file, deploy it and hit deployed application from your browser. But its just "hello world" type app, you most likely want to modify source and play with it. So you'll end up with checking out sources anyway :)

svn co https://svn.java.net/svn/tyrus~source-code-repository/tags/tyrus-project-1.0-b09/samples/echo
cd echo
mvn clean install

Build war file is present in target directory. Please note you might need to disable tests if you are changing functionality (add -Dmaven.test.skip when building sample).

If you want more information, check out Public Review draft (spec api version 1.0-b11), and Tyrus home page.

As usual, if you find some issues/bugs, feel free to file them on our JIRA or send us a note to users@tyrus.java.net mailing list. Any questions about implementation are also welcomed, so if you are stuck at some point when implementing Tyrus based application, don't hesitated and let us know - we should be able to help you.

useful links:

latest Glassfish: http://dlc.sun.com.edgesuite.net/glassfish/4.0/nightly/latest-glassfish.zip
Tyrus homepage: http://tyrus.java.net/
JSR-356 homepage: http://jcp.org/en/jsr/detail?id=356


Pavel Bucek


« April 2014