Errai: The browser as a platform

Thursday, August 6, 2015

Errai 3.2.0.Final released and 4.0 in the making!

Hi everyone,

It's time for a quick update: Errai 3.2.0.Final has been released which contains a number of important fixes and quite a few new features, like runtime template support and an embedded WildFly launcher for Super Dev Mode (see the release notes for all details).

We've also just started work on Errai 4.0! In the short-term, we will be focusing on the following features and enhancements:

  • Errai IoC: Injection of types provided at runtime by dynamically loaded modules (external scripts)
  • Errai IoC: Incremental generation of our bootstrapping logic (to significantly improve refresh times)
  • Errai UI: Ease the integration of web components and allow the use of light-weight DOM wrappers instead of GWT widgets

Max Barkley is back in full force and will be leading most of this development.

What other features or enhancements would you like to see in Errai 4? We rely on your feedback so please join us on Freenode #errai, the errai-dev mailing list, or on our community forums.

Happy coding!

Thursday, February 5, 2015

Upcoming Errai talks

We're happy to announce that there will be three Errai talks this March!

Johannes Barop, a long-time Errai contributor and community member, will present at JavaLand on March, 25. You can find the details of his talk here. If you plan to attend JavaLand (and why wouldn't you? They have Java, beer, and roller coasters!) make sure to stop by and check out his talk!

Harald Pehl, core developer on Red Hat's WildFly team and long-time GWT developer, will present Errai at the Java Users Group in Frankfurt.

Finally, I am really excited and looking forward to presenting at QCon São Paulo on March, 26. The details of my talk can be found here.

Happy coding!

Monday, January 19, 2015

Errai 3.1.1.Final released!

Hi everyone,

Just a quick note that we released Errai 3.1.1.Final today. This is a maintenance release containing a few bug fixes (see the release notes for details). We have also switched master to 3.2.0-SNAPSHOT for future development. So far 3.2 contains a new feature that allows for server-side (dynamic) Errai UI templates. Please stay tuned for more information and an updated roadmap.

Everything is set for GWT.create now and I hope to see many of you in Mountain View and Munich in the coming days!

Happy coding!

Wednesday, January 14, 2015

SSO with Errai and Keycloak.js

The Artificer project ( has been a long-time fan of Errai, relying on it for the majority of our powerful UI. We recently switched to using Keycloak, an out-of-the-box security solution, for authentication and authorization. Typically, you'd protect your Errai index.html page with a simple security-constraint in the WAR's web.xml.  However, due to various issues, we investigated the use of Keycloak's pure-Javascript adapter (keycloak.js). This post will quickly capture the approach and a few gotchas.

Note that Errai has a built-in Keycloak module, based on Errai Security. Although that may be the best way to go, we were interested in making keycloak.js work on its own with plain Errai.


So, first things first.  When you run Keycloak, either using its standalone appliance or within a container of your choice, it serves up the keycloak.js file.  Add it to your page's header:

Right off the bat, there's a few things to notice:

  • The keycloak variable is attached to the window object.  More on that later...
  • The init call includes the {onLoad: 'login-required'} option. This tells Keycloak to redirect users to the built-in login screen, if un-authenticated.  If left off, the user must be pre-authenticated by other means.
  • Keycloak revolves around the use of tokens. Server-side, those tokens expire after a configurable period.  For Javascript-based solutions, such as Errai, that may never refresh the page, manually refreshing the token is vital. However, Keycloak's updateToken is currently asynchronous and uses a promise. Rather than deal with a complicated callback setup, we're simply updating the token on a 10 second timer.  By default, Keycloak tokens expire after a minute, however this value is configurable.


The back-end REST services are also protected by Keyloak.  In order to use them, without requiring basic authentication, the Errai app must provide a "bearer token" on each call.  To accomplish this, we created a RestClientInterceptor to intercept each call and add the token.

Here, we use a bit of JSNI to obtain the Keycloak token from index.html.  Here's where the window object necessity comes in.  Since this interceptor technically runs in a nested frame, simple global variables will not work.  Attaching the variable to window, then referring to it through JSNI's $wnd, allows the cross-frame sharing.

After obtaining the token, the interceptor adds it to the request.  Note that the header key is "Authorization" and the value is "Bearer [token]".  The "Bearer" bit is vital, but can be easily forgotten.


The above approach works similarly for RPC, but is instead based on RpcInterceptor.


What about Servlets?  In our case, Servlets are used directly from GWT FormPanel for needs such as local file uploads.  The Servlets themselves are not protected by Keycloak, but they turn around and call the same REST services described above.  So, the bearer token is still needed, but in a proxied manner. Since there's not a request originating from Errai to intercept, we have to use this workaround.

We automatically add a Hidden input, called "Authorization", to the form.  When the form is submitted, we're re-using the JSNI in KeycloakBearerTokenInterceptor to set the input's value to "Bearer [token]". Then, in the Servlet's doPost, the "Authorization" parameter is pulled from the HttpServletRequest. The token is then used on the proceeding call to the REST services.

One caveat that's often overlooked: if your form sends multipart data, such as our file upload, the "Authorization" parameter is a part of the request's file/form items, not in request.getParameter("Authorization").

For GET, it's obviously easier. Simply add the "Authorization" parameter, identical to the above (if in a form) or by adding it to the URL query string. The Servlet grabs it through request.getParameter("Authorization").

Tuesday, October 21, 2014

Using Polymer's Web Components with Errai

Web Components is an emerging web technology that allows web developers to use custom HTML elements and encapsulation in their applications. Currently, Polymer is the leading web framework that implements this technology. A few members of the Errai community have expressed interest in using Polymer elements in their web apps, hence we spent some time creating an early prototype at Errai Tutorial - Web Components. In this blog post, I will outline the steps needed to use Polymer components with Errai UI in your web application.

Downloading Polymer Elements

Download Polymer and the relevant Polymer components, and place them under src/main/webapp. The Polymer elements and code used in our prototype are located in the components/ directory under src/main/webapp/. Detailed instructions on how to download and update Polymer's libraries and components can be found here.

Using Polymer Elements in Errai HTML Templates

In order to use Polymer elements in your web page with Errai UI, you can create an HTML layout using any combination of Polymer elements and regular HTML elements. For example, this template was created using Polymer's <paper-input> and <paper-button> elements in a <form> element:

The above example will also work with Errai Data Binding. You can further create your own custom element and use it in your HTML template. For information on how to create your own Polymer-based element, see Creating elements - Polymer.

Note: When importing Polymer elements into your app, the polyfill support script (platform.js) as well as the HTML imports required to use each element must be included in your GWT host page.

Integration with GWT

To use Polymer's elements (or your own custom elements) with GWT, we need to create Elements and Widgets, similar to the ones for HTML elements that currently exist in GWT. You can create an Element class for the Polymer element by extending or one of its subclasses. The purpose of this class is to provide Java methods for the Polymer element, by wrapping calls to Polymer's methods and attributes in JSNI code. This Element class represents the Polymer element's DOM implementation.

GWT uses Widget classes that wrap Elements, to provide user interaction capabilities. Thus for all UI-based elements, we need to create a Widget class that extends or one of its subclasses. This Widget class should contain methods to handle user interaction with the Polymer element. Refer to the tutorial and to existing GWT Elements and Widgets for examples on how to create your own custom GWT widgets. Here is an example of how to use the Element class and Widget class to interact with the user and with other widgets in your app. The Polymer element used in this example is the <paper-button>. The example shows how to use the PaperButton Element and Widget classes to add an Enter key handler to the ComplaintForm.

The PaperButtonElement class provides JSNI methods to access the Polymer element's click() method:
The PaperButtonWidget class creates a UI wrapper around the PaperButtonElement:
Finally, the ComplaintForm allows the user to submit the form by pressing Enter, which then calls the methods defined in the PaperButton classes above:

Using Polymer Elements in your web app

As the example in the previous section illustrates, once you have the requisite Element and Widget classes, you can now use the Polymer element as a regular GWT widget in your web page, using @Inject or manual construction. All of Polymer's functionality should be accessible through the Element class, and you can now use the Widget class to make the element interact with the rest of your web app as needed.

Styling Polymer Elements

An important feature of web components is that they provide style encapsulation from the rest of the document. You can take advantage of this feature to style your web components in Errai web apps as well, by using Polymer's style descriptors such as /deep/ and ::shadow (see this link about Polymer styling for more information).

While Polymer's default styling works out of the box, custom styles applied externally to Polymer elements do not. In order to use these styles, you need to add the attribute shim-shadowdom to your style tag. In this tutorial, the shim-shadowdom tag has been added to application.css in the index.html file, to enable external Polymer styling to work.

Note: Currently, while Polymer can prevent styles from leaking out of the element's shadow DOM, styles can still leak into the custom elements' shadow trees. Currently only Google Chrome offers complete style encapsulation. For other browsers, you may need to use custom identifiers to style elements outside of Polymer elements.

The purpose of this Errai Web Components prototype is to illustrate how to use Polymer elements in your Errai web app. This is an early attempt to investigate how Errai can integrate web components into GWT apps. We welcome community feedback, so please feel free to contact us with questions, comments and suggestions regarding the use of Polymer and web components with Errai.