With the introduction of HTML5, CSS3 and fast JavaScript engines, modern browsers have become a powerful platform. HTML5 provides many new standard capabilities for defining the DOM, persisting state locally and communicating with servers, while CSS3 enables a wide range of layout, style and even animation modifications to render the DOM — whole sections of CSS can be conditionally applied depending on client screen size and type of device. JavaScript is no longer a toy but a significant runtime that enables large and complex programs to modify the DOM dynamically, perform business logic and communicate with servers in any number of ways.

These changes have given rise to a new architecture, called “Thin Server Architecture” (TSA), that moves all of the UI logic of a web application — model, view and controller — from the server to the client. So called “single page applications” are now common, where the entire application is downloaded as a single HTML file, with JavaScript controlling flow and hiding and showing parts of the DOM as needed.

JavaScript has a vastly expanded role and, naturally, many libraries and frameworks have appeared, starting the process of building the layered software architectures we are so familiar with, but now in the browser. The variety of libraries in this space is now bewildering and expanding at an extremely rapid pace, requiring strong JavaScript skills and a very significant investment to select a stack.

As a consequence of TSA, the server’s role is shifting from hosting application controller logic (and lots of web pages per application), to serving data — often backed by business logic — using standard protocols such as REST, WebSockets and Server-Sent Events, all of which are available to browser based clients.

Project Avatar

Project Avatar tackles both sides of this equation, providing a JavaScript services layer zeroed in on supporting REST, WebSocket and Server-Sent Events and a rich client side framework that assumes very minor JavaScript knowledge1. The client side is entirely focused on supporting HTML5 and TSA, while the services side is focused on building data services using JavaScript.

JavaScript services are not a replacement for Java based implementations; instead, they are an additional choice in which services can be entirely JavaScript or layered to utilize existing Java libraries. Pure Java services also work well with Avatar clients.



The Avatar framework was designed with abstractions that enable it to be hosted on various runtimes. In the diagram above, the Server Runtime box represents this abstraction layer. The initial implementation uses the Servlet API of an application server — we’ll refer to this implementation below as ‘Avatar EE’.

An Avatar application is comprised of either client side ‘views’, server side ‘services’ or, for convenience, both. Importantly, there is no inherent coupling between views and services, enabling 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.


An Avatar archive is a simple directory structure containing an file and either a views directory or a service’ directory, or both. Avatar contains a built-in system archive which is set as the default parent for application archives, enabling application archives to both extend and even override built-in state.

Avatar supports archives both as file-system directories as well as .zip (or .war) files.

Avatar Services

An Avatar service simply extends either a REST, WebSocket or Push (SSE) abstraction, and the Avatar framework instantiates and invokes it on demand. This is similar in spirit to the Servlet model, but focused on the more modern protocols needed to support HTML5 clients.

Service implementations can leverage built-in Node modules as well as most third-party modules. Since Nashorn supports direct invocation of Java code, the rich set of Java libraries is also available.


Avatar services use an Actor-like concurrency model: multiple threads, with no shared mutable state, communicating using message passing.

Avatar.js applications are both asynchronous and single-threaded (exactly as in Node.js) and require multiple processes to take advantage of multi-core machines. Avatar extends this to enable a much more efficient and natural use of multiple threads, each with an isolated set of JavaScript objects, with requests load-balanced by the framework.

The number of threads created is specified by a service.threads property, with a default of ‘1’ in debug mode, and 'cores-1' in non-debug/production — simple expressions are supported relative to the number of cores on the current machine, e.g. 'cores / 2', 'cores * .75', etc.). Generally, an async (event-driven) server architecture requires far fewer threads than a threaded one, so a value equal to or less than the number of cores is usually sufficient.

A scalable messaging architecture enables communication across threads and will soon be extended to support both the browser as well as clustered server nodes.

Since it is built on Nashorn, JavaScript code in services can directly invoke Java code. This means that the ‘no shared mutable state’ model is not quite accurate (hence ‘Actor-like’), since it is possible to share mutable Java objects across threads. So long as these objects are thread-safe, all is well, but care is required to ensure that this is so.

Another consequence of the ability to use Java code is that some of it is blocking (e.g., and direct use of such code from the async world is a no-no to avoid long pauses in event handling. Avatar provides a simple JavaScript function that will execute any code asynchronously.

Avatar Views

An Avatar view is the HTML and related content required for the browser, along with custom 'data-' HTML extensions and simple JavaScript models. A (server-side) compiler translates the provided HTML into a simple new HTML file plus custom generated JavaScript, as needed.

Avatar EE

Avatar EE enables the full power of Java EE and its APIs to be used directly by developing Java services, or indirectly by using JavaScript APIs in Avatar.


Avatar services support the notion of a data provider. A data provider has a similar interface to an associative array in which values can be stored and retrieved using keys. However, providers can be implemented on different forms of data sources such as text files, distributed caches, databases, etc.

Providers offer developers a tighter integration with both Java SE and EE features without the need to use the JavaScript-to-Java interface. As part of this early access version of Avatar, there is a file provider, and a JPA provider. Other providers are planned for future versions, such as for Oracle NoSQL and Oracle Coherence.

Avatar also includes a JavaScript API to interface with the Java Messaging Service (JMS). JMS in conjunction with WebSocket connections expand the possibilities to interact with client applications, and existing messaging systems can benefit from this new technology. We envision future versions of Avatar providing more “native” APIs to interface with other EE technologies like Context and Dependency Injection (CDI) and even Enterprise Java Beans (EJB). Stay tuned.

The goal is not to create JavaScript APIs for all Java EE technologies, but we want to provide easy access to enough of Java EE if your decision is to write your services using JavaScript. Generally speaking, the JavaScript APIs designed for Avatar tend to be more declarative and provide fewer configuration options than those in Java EE.

Just Enough JavaScript

All you really need to know to use Avatar view models is how to copy and modify example code. If you’d like to understand a little more, read on…

Objects in JavaScript are really just maps: keys are strings, values are primitives, strings, arrays, objects, or… functions. Each key/value pair is referred to as a ‘property’. Objects can be directly instantiated using literal syntax:

var name = {
    first : 'Billy',
    last : 'Talent';

Normally, keys don’t need to be quoted, but the rules are a bit complicated; just watch for errors and add quotes as needed.

Objects can also be declared using constructor syntax:

var Name = function() {
    this.first = 'Billy';
    this.last = 'Talent';
    this.clear = function() {
        this.first = this.last = '';

Note that the property keys have a this qualifier. This keyword is different than the this' keyword in Java. Avatar requires that all constructor property keys use the qualifier; the compiler will throw an error if this pattern is not followed.

The var keyword introduces a variable (obviously) and can be left out; the semantics of each case are different, and it is nearly always correct to use the keyword.

Such constructor functions allow you to make instances using the new operator:

var name1 = new Name();
var name2 = new Name();

Unlike Java objects, JavaScript objects do not have a fixed base class; instead, every object has a special property called prototype, whose value is another object. When you you access a property of an object, if it is not directly available, the prototype object will be searched, and so on up the prototype chain. For example, calling name1.toString() works just fine, because the default prototype is Object, which has the toString method.

The prototype property can be assigned at any time, as can the properties of the prototype object itself — this can be disconcerting for those of us used to static typing.

Functions usually declare argument names (not types), but can reference the ‘arguments’ array instead.

Avatar view models are simply constructor functions. Avatar makes instances for you and assigns a prototype based on the kind of model: ‘local’, ‘rest’, ‘socket’ (WebSocket), or ‘push’ (Server-Sent Event). Each of these prototypes adds many additional functions that are used by the framework.

That’s it — all you need to know about Avatar view models.

Digging Deeper

Of course, there is a lot more to the language; if you are interested in learning more, a good book is ‘JavaScript: The Good Parts’ by Douglas Crockford. The language specification is here, and information on the new Nashorn engine in JDK 8 can be found here.

For more detail about the this qualifier, please see here.

For the adventurous, there is a lot more you can do with Avatar view models, especially overriding prototype methods: check out the reference docs for the rest, socket, and push prototype objects.

1It may seem contradictory to provide a solution that assumes minimal JavaScript skills on the client alongside one that requires proficiency on the server. However, we think this makes sense since very often these two parts of an application are implemented by different teams, with different skill sets.

The Avatar client provides a very gradual on-ramp to JavaScript development: a simple copy-and-paste approach is sufficient to create most applications, but as you become more comfortable with the language, it’s easy to override and extend the framework in powerful ways.

Back to top