Project Avatar – The next Java EE Feature?

It is this time of the year again. Christmas holidays are approaching fast and the Java Advent Calender is filling up constantly. Today it’s on me to write my surprise post. I’m Markus, also known as @myfear and I’ve been working with and around Java EE and a bunch of related servers since many years. Beside the daily work I started more actively contributing to the Java EE Expert Group with the Java EE 7 release. With EE 7 out the door since a while it is already time to start planning for the next revision of the platform which will most likely be called Java EE 8. Oracle set up a community survey with which they would like to get input from the community on the relative importance of some of the features they intend to add. First of all this should encourage the interested reader to participate and take the survey. One particular point in it is all about support for HTML 5 based, dynamic applications. While WebSocket and JSON Processing already made it into Java EE 7 there is another feature particularly in GlassFish and WebLogic (via Jersey) at the moment which has some potential to be standardized. The Server Sent Events (SSE). It already is part of the HTML5 spec and would be a very good candidate for standardization. But Oracle is thinking even further and is asking if there would be enough support and interest to actually standardize the use of JavaScript on  Java EE servers. When this kind of question started to appear at JavaOne 2012 it was basically referred to as Node.jar on Nashorn. Since this September we know the real name: Project Avatar.

Avatar At A Glance
Project Avatar provides a JavaScript services layer zeroed in on supporting REST, WebSockets and Server-Sent Events, and a rich client side framework that assumes very minor JavaScript knowledge. The services side is focused on building data services using JavaScript, while the optional client side is entirely focused on supporting HTML5 and TSA (Thin Server Architecture).

Project Avatar (Source:

Thin Server Architecture
With the introduction of HTML5, CSS3 and fast JavaScript engines, modern browsers have become a powerful platform. In the advent of the so called single-page application (SPA), also known as single-page interface (SPI) the design of modern user interfaces shifted away from server side generation to web applications or web sites that fits on a single web page with the goal of providing a more fluid user experience akin to a desktop application. An SPA moves logic from the server to the client. This results in the role of the web server evolving into a pure data API or web service. This architectural approach has been coined “Thin Server Architecture” to indicate that complexity moved from the server to the client while reducing overall system complexity.

What is really in Avatar?
But Avatar is far more than just a TSA approach. It basically consists of three parts. The foundation is build by the upcoming Java 8 and it’s included JavaScript implementation called Nashorn. On top of it is the Avatar Runtime including an additional compiler layer and a Servlet API based server. Those abstractions  enable it to be hosted on various runtimes. Avatar applications are comprised of either client side ‘views’, server side ‘services’ or both. Importantly, there is no inherent coupling between them which enables views to communicate with existing services and for services to be consumed by any type of client. An application ‘archive’ is deployed on the server and is compiled to generate JavaScript tailored to the application. Generated JavaScript for views handles data-binding with the DOM/UI as well as data-management to remote services and local storage. The Avatar archives are somewhat similar to Java EE web-archives. They consist of a WEB-INF folder, an file in the root and either a views directory and/or a service directory. Both file-system directories or .zip (.war) files are supported by Avatar.

All that is left on the Server – Services
An service extends either a REST, WebSocket or Push (SSE) abstraction and it’s life-cycle is completely handled by the framework. Service implementations can leverage built-in Node modules as well as most third-party modules. Thanks to Nashorn’s support for direct invocation of Java code you can also use most Java libraries directly.

The Client Side – Views
A view is the HTML required by the browser. It also contains custom ‘data-‘ HTML extensions and simple JavaScript models. Those views get translated by a (server-side) compiler before sending the complete SPA HTML file including the custom generated JavaScript to the browser.

Putting it all together. A Simple Example.
Oracle provides a decent set of examples and documentation for Avatar which basically is enough to get you started. First thing to try it out yourself is a JDK 8 Early Access Build for your OS. At the time of writing I tried it with the latest Developer Preview b118. After installing you need to get the latest GlassFish Open Source Edition 4.0 server and unzip it into a suitable location. Make sure it runs with the installed JDK 8 by either putting <jdk8>/bin to your PATH environment variable or adding the following entry to the <gf4>/glassfish/config asenv.bat/conf

set AS_JAVA=<jdk8>

No go ahead to download latest and expand it to the <gf4>/glassfish/ directory. After that you need to set a AVATAR_HOME environment variable and point it to the <gf4> install directory. And make sure to add %AVATAR_HOME%glassfishbin to your PATH environment variable.
If all of that is done you can switch to your workspace folder and issue the following command to have Avatar creating a simple example app for you:

avatar new --example=hello

It creates a basic “hello” application which only consists of a view. It is a good place to start exploring and you can directly start your Glassfish instance afterwards and deploy the application as you would with every typical Java EE application:

asadmin start-domain

asadmin deploy hello

The “hello-example” app.

Pointing your browser to http://localhost:8080/hello will display the application. You can start editing the view located at <workspace>/hello/view/src/hello.html directly. While the server is running Avatar takes care of re-compiling it directly for the next request. This ensures a rapid development. This behavior is controlled by the “debug=true” property in the file and can be altered for productive systems. Further on, setting it to false causes all .js and .css files to be minimized before delivery.
At least if you first download and add the required YUI Compressor (jar download) to Avatar first. Due to license restrictions it hasn’t been bundled. Simply put it into <gf4>/glassfish/modules/avatar-ext/lib. You might need to create that directory first.

Beside this very simple example without any service at all there are more complex ones available with the distribution at %AVATAR_HOME%/Project-Avatar-examples/. For convenience reasons there is a complete examples.ear available which can be directly deployed and tested. To access the samples simply prefix the example name with “demo-“. So the “rest” example can be accessed via http://localhost:8080/demo-rest/.

TodoMVC – Example App with Avatar

You have to look out for different features to be showcased in the different examples. If you want to know how Avatar handles persistence you can exactly look into the rest example which uses a FileDataProvider to save the items. Another interesting example is the TodoMVC based app (http://localhost:8080/demo-todo/). It showcases a more complex view which also has been styled.

What is next?
As of today nobody knows what is going to happen with Avatar. The community feedback hasn’t been tremendously loud or excited in general. I guess the reason for it is that nobody really knows what to do with it. The biggest drawback as of today is, that it only runs with GlassFish which will further limit adoption and community interest. Given the fact, that SSE isn’t part of the Java EE specification it might make it even more difficult to port it to other app-server. Even if the license (GPL2 with Classpath Exception) should allow it. Back to the initial survey and the thought about specifying a server side JavaScript integration with Java EE, you know at least have a brief idea about what Oracle is talking if they are talking about Avatar. Go ahead and take that survey and tell them what you are thinking about having that kind of stuff in Java EE.

I wish you a happy holiday season and a new year filled with peace and prosperity.

Meta: this post is part of the Java Advent Calendar and is licensed under the Creative Commons 3.0 Attribution license. If you like it, please spread the word by sharing, tweeting, FB, G+ and so on!