Errai 4.1.0.Final Released

We've recently released Errai 4.1.0.Final, the first release on master since branching off the 4.0.x series. In this short post, I will highlight some of cool new things you can find in 4.1.0.Final, which include:

• Size and performance improvements in code generated for Errai Marshalling and Errai Data Binding
• Custom content delegation in Errai Navigation
• ErraiApp.properties moved to META-INF
• Templating and Data Binding support for Elemental 2

The best part: two of these changes were delivered by our fantastic community. Read below for descriptions about these features. At the end I will talk briefly about forward-development currently happening in Errai.

Marshalling and Data Binding Improvments

Both Errai Marshalling and Data Binding use generated code to introspect and access members of annotated classes. In Errai 4.1.0.Final, this code has been refactored to decrease generated code size and better take advantage of optimisations for String literals in the GWT compiler.

If you use Errai Marshalling or Data Binding heavily, Errai 4.1.0.Final should noticeably decrease the size of your JavaScript payload. A big shout out to slavap for this excellent contribution!

Custom Content Delegation

Errai Navigation provides lots of page-specific mechanisms for hooking into the navigation lifecycle, but until now there were no convenient ways to generically customize how all pages were shown or hidden.

Errai 4.1.0.Final introduces a content delegation system. Users can override a ContentDelegation interface and replace the default implementation to insert their own custom logic for displaying and hiding all pages. The delegation is quite flexible, even allowing for asynchronous actions.

A big thanks to BenDol for the concept and implementation of this feature!

Configuration Moved to META-INF

By convention, configuration files that don't require name-spacing are supposed to be placed in the META-INF folder. Errai 4.1.0.Final supports scanning ErraiApp.properties files in the META-INF folder, allowing users to follow this convention. Moving forward, you should consider this a best practice.

Errai 4.1.0.Final will still work properly with ErraiApp.properties files outside of a META-INF folder, but you may see an abundance of warnings in your logs, as we will likely phase out support for this in our next major release.

Elemental 2 Support for Templating and Data Binding

Elemental 2 is a project that exposes built-in web APIs in Java. Like the first Elemental, the project is automatically generated from external definitions of web APIs. Unlike its predecessor, Elemental 2 uses JS Interop.

Back when we began work on Errai 4, Elemental 2 was not yet available. We didn't want that to slow down our work on HTMLElement-based user interfaces and JS Interop support, and so we created a collection of hand-written element wrappers in Errai.

But now that Elemental 2 is available, it is in the best interests of the GWT community to standardise around these. As such, Errai's DOM wrappers have been deprecated and we have added full support to templating and data-binding for classes from Elemental 2.

We will not be removing the Errai element wrappers, but we will also not be updating them, and you are highly encouraged to use Elemental 2 going forward.

Looking to the Future

The biggest priority for Errai in the coming months is preparing for migration to GWT 3. We've known for some time that GWT 3 will require big changes to the way we develop GWT applications. There probably won't be GWT Widgets. There definitely won't be GWT Generators.

We've already made large strides towards GWT-Widget-less UI development. Although there is some more work to be done here, we are also beginning progress on the even larger and equally important task: migrating Errai's GWT generators to annotation processors.

I'd like to take this opportunity to mention recent addition to our team, Tiago Bento, who has been the driving force behind our APT migration efforts. It's not quite ready for a test drive yet, but keep an eye out in the future for blog posts about how to try out Errai annotation processors on our snapshot releases.

Until the next time, happy coding!

Errai 4.0.0.Final released!

Today I'm thrilled to announce that Errai 4.0.0.Final has been released!

At a glance, here are the big changes from Errai 3 to 4:

• Uses GWT 2.8.0 and WildFly 10 for Super Dev Mode
• Has a new Errai IoC container supporting incremental code regeneration, and greater compliance with CDI
• Has advanced JS Interop support, including dependency injection of native JavaScript objects, and templating and data-binding with JS Interop wrappers of DOM elements and web components
• Has message bus enhancements (better clustering support and CSRF protection)

All of these changes have been discussed in previous blog posts. Nonetheless, in this post I will summarise these changes with links to the more detailed descriptions.

New Errai IoC Container

Errai 4 has a new IoC container, that supports incremental regeneration of code. The main benefit of this is to improve the performance of refreshing during Super Dev Mode. But this rewrite also allows for the possibility of migrating to annotation processors for all code generation in a future release.

The new IoC container also more closely aligns with CDI:

• @ApplicationScoped beans must be proxiable, and are lazily loaded like in Weld
• @Singleton is a "pseudo-scope": it need not be proxiable but cannot be part of a circular injection
• @Typed annotation is supported

In some cases, beans may be resolved slightly differently than in Errai 3. Our upgrade guide highlights some important "gotchas" to look out for when upgrading to Errai 4.

Advanced JS Interop Support

The overarching theme of Errai 4 is working directly with JavaScript APIs and the DOM via JS Interop. If you don't already know about JS Interop, I encourage you to watch the first half of this talk by Daniel Kurka at GWTCon.

Here are the ways in which you can use JS Interop with Errai 4:

• Use JS Interop interfaces for DOM elements or web components as @DataFields in @Templated components
• Use JS Interop interfaces for DOM elements or web components as @Bound UI components with Errai data-binding
• Inject JavaScript objects into your application like normal GWT/Java objects

You can read more about Errai 4 JS Interop support here and here, or view examples in the Errai Tutorial.

Message Bus Enhancements

The Errai message bus has received some love in Errai 4, with fixes that improve fail-over behaviour in clustered setups, and optional built-in CSRF protection.

Both of these are described briefly in this blog post.

Thanks to the Community

I'd like to end by thanking everyone in the Errai community who contributed to the quality of this release, through pull requests with new features and reports of important issues in our beta and candidate releases. In particular, the Errai JS Interop support was greatly improved by the important feedback from our community.

Until the next time, happy coding!

Errai 4.0.0.CR2 released!

As of today Errai 4.0.0.CR2 is available. This release contains mostly bug fixes and enhancements to some of our demos.

Below are some of the highlights.

Fix Maven Parallel Build Issues

Previously doing a parallel Maven build of an Errai project could occasionally lead to compilation failures. This release provides a fix so that parallel builds can now reliably execute on Errai projects.

Add Jetty Profiles Back to Errai Demos

During the migration from GWT 2.7 to 2.8 many Errai demo Jetty configurations stopped working, and consequently they were simply removed. Thanks to Dmitrii Tikhomirov, many of the Errai demos now have Jetty profiles once more so you can see how to build an Errai application for deployment outside of a Java EE app server.

Source Translation of Stack Traces in Google Chrome Fixed

A bug in Errai logging had broken source mapping of stack traces in errors logged through Errai. The result was that stack traces printed to the console in Google Chrome would only show obfuscated method names and line numbers. The problem has been fixed so that stack traces logged to the console once again use source maps to show line numbers from the Java source.

Stay Tuned

Stay tuned as we get closer to our first final release of Errai 4. Until then, happy coding!

Errai 4.0.0.CR1 released!

Since our last post we've done several beta releases, but today I'm happy to announce our first candidate release of Errai 4! Since we haven't blogged about our last few Beta releases, this post will contain highlights of all the changes introduced since 4.0.0.Beta4.

• Client-side support for the CDI @Typed annotation
• Global translation keys for Errai i18n
• Removed ResponseCallback
• Message bus enhancments (better clustering and CSRF protection)
• General purpose gatekeepers on @Pages

Without further ado, let's dive right in.

Client-side support @Typed

The @Typed annotation allows you to restrict the types of injection sites that a bean may satisfy. What does that mean? To explain, we'll use the example from the @Typed javadoc. Consider the following class:

With normal CDI resolution, this bean will satisfy any unqualified injection site for any the following types, because the bean is assignable to any of these: Shop, BookShop, Business, and Object. Typically this is desirable, but we could reasonably want this bean to only satisfy injection sites of type Shop so that other developers don't depend on the implementation.

The @Typed annotation allows us to specify a subset of this bean's assignable types as its bean types, like so:

With this declaration, BookShop now only satisfies injection sites with types Shop or Object, preventing other developers from injecting this as a BookShop or a Business.

Global Translation Keys in Errai i18n

If you use Errai i18n, then you know that translation bundles use templated class names as prefixes for the keys. For example, consider this templated bean.

If we used Errai i18n to translate the "hello" data-field, we would define the translation of this element with the key "I18nTemplatedBean.hello-key". The disadvantage of this prefixing is that it made it impossible to share translations of common words between templates, leading to lots of duplication.

Now Errai i18n supports unprefixed translation keys that can be used in any template. Global translation keys have a lower priority than prefixed translations, and so they will only be used to translate a data-field if there is no translation key for the field specific to that template. So we could use the value associated with the key "hello-key" to translate the data-field in the above example provided there is no value for the key "I18nTemplatedBean.hello-key".

No more ResponseCallback for JAX-RS RPCs

The ResponseCallback was introduced to Errai to allow developers to access the underlying Response object returned from a JAX-RS RPC call. Unfortunately, this feature caused a serious problem for client-side RPC interceptors (including those used by Errai Security), where it became impossible to intercept the result of an RPC calls without a ClassCastException in some cases.

To solve this problem, we've removed the ResponseCallback, so that every RPC method has a single expected callback type that directly corresponds to the return type of the RPC method. In cases where a Response object is needed, you can modify your JAX-RS method to return a javax.ws.rs.core.Response, allowing you to use a RemoteCallback<com.google.gwt.http.client.Response> from the client call site.

Message Bus Enhancements

Clustering Fixes

This release fixes a bug where the message bus could enter a reconnect loop after failover in certain clustering setups. With this fix the message bus is now more resilient at handling failover when working behind a load balancer.

CSRF Protection

The Errai Bus now provides basic CSRF protection. This protection is disabled by default. It can be enabled setting this property to true (as a System property or in ErraiApp.properties): errai.bus.enable_csrf_token

When enabled, a CSRF token is generated on the server that must be included as a header in every bus request. This token can be embedded on a GWT host page with a provided filter, or else negotiated as part of the message bus connection.

General purpose gatekeepers for @Pages

Since the release of Errai Security it has been possible to control access to pages via required roles, but there was no general way to redirect before a page was displayed based on business logic.

As a recent change, you can now intercept navigation by adding a NavigationControl parameter to a @PageShowing method like so:

We on the Errai team would like to thank Ben Dol for both suggesting and implementing this feature.

Still Time for Feedback

As always, we encourage and welcome community feedback. If you are still on Errai 3, consider checking out our migration guide and trying out Errai 4 today!

Until the next time, happy coding!

Errai 4.0.0.Beta4 released!

Greetings!

Errai 4.0.0.Beta4 is now available. This release contains mostly bug fixes, but here are some noteworthy changes:

• Upgrade GWT to 2.8.0 and Guava to 20.0
• The Errai Tutorial now showcases Errai's JS interop integration

Errai Tutorial Enhancments

A major vision of Errai 4 has been more support for working directly with the DOM and more support for using JS interop. With this latest round of enhancements, the Errai Tutorial now showcases this vision and below I'll highlight some of the major features in action.

UI Components without GWT Widgets

The Errai Tutorial now showcases UI components built without any GWT widgets [1] [2]. These components are built with Errai templating using JS interop wrappers for interacting with the DOM; Element wrappers are used in place of GWT widgets and DOM events in place of GWT widget events.

One big advantage of this approach is that the markup of these UI components at runtime is exactly the same as the template HTML. Because GWT widgets are often implemented with multiple tags and custom CSS classes, using widgets as @DataFields can result in UI components rendering differently than their templates render when viewed outside the application.

Custom JS Interop Wrappers for DOM Elements and Web Components

The Errai Tutorial demonstrates how you can integrate web components with your Errai app, and how you can write your own custom element wrappers with specialized data-binding behaviour.

The tutorial now uses the Polymer paper-input and paper-textarea web components as part of a @Templated form. These components can be injected and used as @DataFields (as they are here). By using Errai's new HasValue interface for native @JsTypes with the @JsProperty annotation, these wrappers declaratively instruct Errai to use the "value" property of the paper elements for data-binding.

The tutorial also includes custom anchor element wrappers that showcase more complex data-binding behaviour. The BindableEmailAnchor is a wrapper for an anchor element that uses HasValue and @JsOverlay so that @Bound instances will display an email address as a mailto link as well as in the anchor text content.

Since the @JsOverlay method implementation is the only code generated by the GWT-compiler for a native @JsType, this is a light-weight way to declare element interfaces with custom data-binding behaviour.

Uses JQuery to Demonstrate Third-Party JavaScript Integration

The Errai Tutorial has a wrapper for a small subset of JQuery to showcase third-party JavaScript integration. With only a single @Produces annotation added to the JQuery wrapper, it is possible to inject the JQuery function for use in GWT code.

In general, we on the Errai team believe that using dependency injection is a best practice, but this is especially important with native JavaScript objects. By injecting the JQuery function rather than accessing it through a static method, it is much easier to mock out that object and test the code using it in a Java SE environment.

Try It Out and Give Us Your Feedback

We encourage you all to check out Errai 4.0.0.Beta4 and our new tutorial and share with us your feedback, whether that feedback is bug reports to our JIRA page, or more general disucssion in our forum.

Until the next time, happy coding!

Errai 4.0.0.Beta3 released!

Greetings!

Today we have the pleasure of announcing a new Errai release, 4.0.0.Beta3. Some important highlights in this release are:

• GWT version upgraded to 2.8.0-rc2.
• support for different merging strategies on @DataField attributes.
• support for JS interop DOM event wrappers for @EventHandler methods.

Without any delay, let's talk about what these changes mean for you.

GWT Version Upgrade to 2.8.0-rc2

If you tried using Errai 4.0.0.Beta2 with GWT 2.8 snapshots or 2.8.0-rc2 you may have experienced issues running Super Dev Mode because of transitive dependency conflicts between GWT and Errai. These issues are resolved in 4.0.0.Beta3.

Data-Field Attribute Merging Strategies

When Errai initialises a templated bean, it merges attributes of data-fields in the HTML file with attributes on @DataFields in the @Templated Java file. In previous versions, attribute values of the data-fields in the HTML file always overrode @DataField attribute values. For example, for the Errai template below, the value of the title attribute at runtime would be "template".

As of this release, you can select between two strategies: USE_BEAN and USE_TEMPLATE.

Merging Single-Valued Attributes

For most attributes, USE_TEMPLATE (the default) causes merging to happen as in previous Errai versions: attribute values on a data-fields in the HTML file will override values of the respective @DataFields.

Conversely, the USE_BEAN strategy will preserve attribute values from the @DataField, only copying attribute values from a data-field in the HTML template if that attribute is not set in the respective @DataField.

You can declare which strategies to use as part of the @DataField annotation, with the ability to specify strategies for specific attributes, or a default strategy for all other attributes. In the example below, the "title" attribute will keep whatever value is set on the @DataField and all other attributes will have the value from the template data-field.

Merging List-Valued Attributes

Both strategies behave a bit differently when merging the "style" and "class" attributes because these attributes have list values.

When merging class values, all class names from the template and Java field are preserved. In other words, all CSS classes are combined between template data-fields and Java @DataFields regardless of which strategy is selected.

For example, below the "container" div will have the following classes (even if a different merging strategy was specified on the @DataField): "template bean both"

When merging style properties, individual CSS rules are kept from both the Java @DataField and the template data-fields as long as they do not conflict with each other. When there is a conflict, the selected strategy is used to resolve it, where USE_TEMPLATE causes the HTML data-field style value to win, and USE_BEAN causes the Java @DataField value to win.

In the example below, the "container" div will have the following style after the merging strategy is applied: "color: red; font-weight: bold; background-color: black"

JS Interop DOM Event Wrappers

In this release we have introduced a @BrowserEvent annotation for defining a native @JsType as an interface for a DOM Event. Annotated types can be used with the @EventHandler annotation to define methods as event listeners similarly to how @EventHandler is used with GWT Widget events. Several @BrowserEvent interfaces can be found in errai-common, covering the more common DOM event interfaces.

Below is an excerpt from the MouseEvent interface in errai-common.


Unlike GWT Widget events, multiple kinds of DOM events can share the same interface. The @BrowserEvent value for MouseEvent specifies the names of DOM events for which MouseEvent is an interface.

Because of this many-to-one mapping, declaring a handler method with a @BrowserEvent works similarly to declaring a native GWT event. There is a new @ForEvent annotation that is used to specify for which DOM event a handler should listen (which is analogous to @SinkNative for native GWT events).

An @EventHandler with a @BrowserEvent type can be registered for any data-field in the template HTML file, whether or not it has a corresponding @DataField in the Java bean.

Next Steps

Keep an eye out for upcoming blog posts focusing on some of the more advanced new features in Errai 4 such as JS interop support.

Until then, happy coding!

Errai 4.0.0.Beta2 released!

Salutations!

Today we're happy to announce the release of Errai 4.0.0.Beta2. This release includes lots of little fixes and enhancements including:

• The EmbeddedWildflyLauncher for Super Dev Mode has been upgraded to use WildFly 10
• Errai Navigation has new annotations for linking native anchors to Errai Navigation pages
• Improved code-generation performance
• Better support for declarative data-binding to native DOM elements
• An injectable ManagedInstance for dynamically creating bean instances that manages the instances' life-cycles

Below we'll explain what some of these changes mean before talking about next steps.

WildFly 10 Upgrade

The EmbeddedWildflyLauncher now support WidFly 10+. Because of API changes in WildFly, it was not possible to maintain backwards compatibility with WildFly 8. That means that you have two options when upgrading Errai to 4.0.0.Beta2.

Upgrading to WildFly 10 (Recommended)

If you use the same WildFly configuration shown in the Errai Tutorial then you need only upgrade the as.version property to 10.0.0.Final. If you have any other configuration, just make sure that the errai.jboss.home system property in your Super Dev Mode configuration points to the root of a WildFly 10 installation.

Don't Upgrade errai-cdi-jboss

If you can't migrate to WildFly 10 right away, you can use an older version of errai-cdi-jboss (which contains the launcher) while still using the newest beta release for all other Errai jars.

Errai Navigation Links with Native Anchors

Errai Navigation has two new annotations that you can use on native Anchors for linking to Errai Navigation pages:

• org.jboss.errai.ui.nav.client.local.api.TransitionTo
• org.jboss.errai.ui.nav.client.local.api.TransitionToRole

These annotations are meant to replace the widget-based TransitionAnchor. Below we show them used in an Errai UI templated bean.

The first anchor links directly to the FAQPage while the second links to the page with the DefaultPage role. As with the previous transition anchors, Anchors with TransitionTo or TransitionToRole are validated at compile-time.

Better Data-Binding Support for Native DOM Elements

There were two issues with declarative data-binding of native elements in Errai 4.0.0.Beta1:

• @Bound on a native element would fail in some cases for beans that were not @Templated
• @Bound(onKeyUp=true) on an input element (TextInput, NumberInput, etc.) was not supported (and would cause compilation errors)

Both of these issues are fixed in 4.0.0.Beta2, moving Errai two small steps closer to the goal of GWT widget-free UI development.

Creating Beans Dynamically with Managed Life-Cycles

Errai supports CDI's Instance<T> for dynamically creating bean instances, but this API has some practical issues:

• An instance created by an Instance<T> is managed by the caller. The caller is responsible for destroying the bean, which can lead to memory leaks.
• Calling destroy on an Instance<T> destroys a bean regardless of its scope. But usually it is only desirable to destroy @Dependent beans, since @ApplicationScoped beans tend to be used throughout the entire runtime of an application.

Errai 4.0.0.Beta2 includes a new ManagedInstance<T> interface with similar methods but slightly different semantics that aim to simplify dynamic bean creation:

• The destroy method on ManagedInstance<T> destroys @Dependent instances and is a no-op for all other scopes.
• ManagedInstance<T> has a destroyAll method that destroys all @Dependent instances created by it.
• When a ManagedInstance<T> is destroyed, its destroyAll method is called. A ManagedInstance<T> is destroyed when the bean it is injected into is destroyed.

In case the significance of that last point isn't immediately clear, this means that every dynamically created @Dependent instance from ManagedInstance<T> is cleaned-up when the type that injected that ManagedInstance<T> is destroyed. This avoids memory leaks and boiler-plate in short-lived components that create dynamic instances (like lists of UI elements).

Next Steps

In the coming weeks here are some of the features and tasks we will be working on:

• Support for a new scope bound to Errai Navigation @Page life-cycles
• Thin DOM wrappers for browser events supported by Errai UI @EventHandler
• Configurable strategy for merging @DataField element attributes
• Testing with the newest GWT 2.8 snapshots and releases

In the interim, please try out Errai 4.0.0.Beta2 and tell us what you think.

Happy coding!

Errai 4.0.0.Beta1 released!

Greetings everyone!

As we write this, GWT and Errai are 10- and 6-years-old projects respectively. In those years, the web development community has progressed at an amazing speed, which has led some to ask the question: Is there still a place for these projects now and in the future?

We on the Errai Team continue to see huge value in our type-safe and declarative programming model for developing large projects. It is because of this value that we continue to actively develop Errai and it is because of this value that we continue to say this.

Today we're happy to announce the release of Errai 4.0.0.Beta1, targeting GWT 2.8.0-Beta1. This release brings exciting new features for working with native JavaScript and HTML, as well as improved refresh times in Super Dev Mode. In particular, 4.0.0.Beta1 includes:

• A new Errai IoC container supporting partial code regeneration for improved refresh performance in Super Dev Mode

• Greater compliance with CDI such as:
• Lazy singleton support (the new default for @ApplicationScoped beans)
• More CDI-like resolution of IOC beans

• Support for injecting native JavaScript objects into IoC beans with JS interop

• Support for injecting Errai IoC beans across separately compiled GWT scripts

• Support for native DOM-based UI development with:
• JS interop wrappers for common DOM elements
• A declarative way of defining custom element wrappers available for injection in Errai IoC
• Ability to use native DOM elements with Errai UI @DataFields, Errai Navigation @Pages, and Errai Data Binding @Bound fields

So what do all these changes mean for you?

Performance Improvements

When developing in Super Dev Mode, refreshing after modifying an IoC managed type requires generating significantly less code, decreasing the overall refresh time.

At runtime, applications with many @ApplicationScoped beans will notice decreased start-up times as @ApplicationScoped beans are now lazily instantiated by default.

Templated Beans with Native HTML Elements

In Errai 4 it's now possible to develop UI components without Widgets, and instead with thin-wrappers around native HTML elements. Here is a @Templated bean for a form using Errai UI and Data Binding.

How is this different from Errai 3?

• Div, TextInput, and TextArea are not Widgets. Rather they are thin-wrappers around the div, input, and textarea elements respectively (using the GWT 2.8 JS Interop API)
• The ContactForm does not extend Composite
• The root element of the template is accessible as a @DataField. (This can be used to manually add this template to the DOM.)

Injecting Other DOM Elements

Errai 4 provides built-in thin-wrappers for most commonly used HTML elements, which you can you use in place of Widgets. The complete collection can be found in this package.

In case you wish to inject elements which do not have specific wrappers provided by Errai, you may use either of the following options.

Use the @Named Qualifier

Using the @Named qualifier, it is possible to inject an HTMLElement with any tag name. For example, here is how you could inject a nav element.

Create your own @Element

It's also very simple to declare your own thin DOM wrappers using the new @Element annotation. For example, here is a thin wrapper for the nav element that, if included in your project, can be available for injection in the IoC.

Next Steps

For those of you itching to learn more, our next blog post will take a deep dive into native JavaScript support in Errai 4, including how you can make arbitrary JavaScript objects injectable and how you can inject Errai IoC beans across separately compiled GWT scripts.

Until then you can check out our new and improved Errai Tutorial, which showcases all of the features mentioned here.

Happy coding!

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!

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!

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!

SSO with Errai and Keycloak.js

The Artificer project (http://artificer.jboss.org) 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.

index.html

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.

REST

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.

RPC

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

Servlets

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

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 com.google.gwt.dom.client.Element 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 com.google.gwt.user.client.ui.Widget 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. 

Errai 3.1.0.CR1, 3.0.2.Final and 2.4.5.Final released!

Today we're happy to announce three new Errai releases!

Errai 3.0.2.Final and 2.4.5.Final are maintenance releases containing fixes to all reported problems. 3.0.2.Final also contains significant performance improvements for development mode. Browser refreshes to load changes should be significantly faster on average due to a newly introduced caching mechanism and several classpath scanning optimizations.

Errai 3.1.0.CR1 contains all the same fixes and improvements as well as number of new features requested in our forums.

• Support for JSR-356 WebSockets: ErraiBus can now leverage JSR-356 WebSocket support when available (i.e. in WildFly 8.0 or higher). Check out our reference guide for details. Thanks to Michel Werren for the pull requests!
• Built-in offline manifest linker: Errai now provides an offline linker to generate HTML5 cache manifest files at compile time.
• PushState support in Errai Navigation: Errai Navigation can now optionally leverage HTML5 pushState (using Johannes Barop's great GWT library). This allows for more flexibility when designing your page URLs (i.e. you can now make use of path parameters).
• Errai Security Enhancements: Errai Security now has a Keycloak integration module for SSO support and allows for fine-grained authorization rules.

The last item deserves more details. So, here they are, provided by Max Barkley who also did most of the implementation work:

Errai Security provides a uniform, declarative syntax for securing RPC Services, Messaging Services, Navigation Pages, and UI elements (you can read more here). We've listened to your feedback and have some new features in Errai Security.

Fine-Grained Authorization with Custom Roles

In Errai 3.0, roles must be specified as String constants. In Errai 3.1, it is now possible to define a RequiredRolesProvider that can return your custom implementation of the Role interface. By overriding the equals and hashcode methods with your own role matching logic, it is now possible to create more fine-grained authorization rules.

Here is an example two RPC Services that both require the same roles, but one uses the String role syntax while the other uses a RequiredRolesProvider:

Note that implementations RequiredRolesProvider will be looked up through the bean manager, so they can inject dependencies and use other IOC features.

Keycloak SSO Integration

JBoss Keycloak is a framework that makes Single Sign On (SSO) and Social Media logins a walk in the park. In Errai 3.1, Errai Security has a keycloak module that provides an implementation of the AuthenticationService that can accept logins from Keycloak.

The best part is that you can still use this feature with the PicketLinkAuthenticationService (or your own custom implementation) if you want to also allow logins from your own database. When added to the classpath, the KeycloakAuthenticationService will wrap any other AuthenticationService it finds. This way, you can either direct your users to a Keycloak server for SSO, or call the AuthenticationService.login method to log in through an alternate service.

You can read about configuring Keycloak with your app here, or follow this README to see it in action with the Errai Security demo.

Happy coding and please keep the feedback and feature requests coming!

Errai 3.0.0.Final released!

Today we're excited to announce the Errai 3.0.0.Final release! Don't worry if a feature you wanted didn't make it in yet. We'll switch our master branch to 3.1.0-SNAPSHOT where we'll be working on new features and merging your pull requests ;). Fixes will also be released as 3.0.x, if required.

Check out the release notes for details on all fixes and improvements of this release. Also make sure to read our recent blog posts introducing all new features of Errai 3.0 (Part 1 on RPC enhancements, Part 2 on Errai Security, Part 3 as a summary of smaller features, and a description of our Forge Addon).

A big thank you to everyone who contributed features and patches as well as everyone who provided feedback and shared their experiences with us. We love working on open source.

Please join us on Freenode #errai, the errai-dev mailing list, or on our community forums.

Happy Coding!

What's new in Errai 3? Part 3: The Smaller (But No Less Powerful) Features

This is the third post in a series describing new features in Errai 3.0. This post is a summary of some of the smaller features and enhancements coming in 3.0.0.Final.

Improved HTML Form Support

Asynchronous form submission can make it difficult to trigger useful events in the web browser (such as prompting to remember a user's password). To help you overcome this issue, Errai UI now contains a base class for @Templated Widgets that provides better HTML form support.

By extending the AbstractForm class and invoking its submit method, Errai simulates native HTML form submission. Below is an example login form that causes modern browsers to prompt the user to remember a password when the "Login" button is clicked.

Test Generation with the Errai Forge Addon

If you haven't heard, there is an Errai Addon for JBoss Forge 2. This addon can set up Errai in an existing Java project for running in Dev Mode or compiling to production mode. But in the 3.0.0.Final release, you will be able to use the addon to generate unit and integration tests.

Unit tests are generated with GWT Mockito. Mockito is a test framework that allows you to inject mocks into classes and assert conditions on how these mocks are used. GWT Mockito adds extra GWT compatibility, allowing you to test classes with GWT.create calls or JSNI methods.

Integration tests extend the AbstractErraiCDITest (which in turn extends the GWTTestCase). In addition to the normal GWTTestCase functionality, the AbstractErraiCDITest initializes the Errai framework, including the Message Bus and IoC/CDI container.

WildFly 8.0 Support for Dev Mode

Previously we announced an improved Dev Mode setup using the JBossLauncher. This setup allowed the GWT Dev Mode to control a full JBoss 7 instance, making it easier to develop a GWT app using Java EE on the server.

It is now possible to use the this launcher with WildFly 8.0. If you haven't yet, give it a try since there have been many performance improvements to WildFly 8.0 that make a noticeable difference in startup time.

Asynchronous IOC with Fragment Control

Errai's @LoadAsync annotation allows for managed beans to be loaded asynchronously. That means the code for these beans will reside in a separate JavaScript file that will be downloaded the first time it is needed. In Errai 3.0.0.Final you have more control over these split points. A code fragment name can optionally be specified using a Java class literal (i.e. @LoadAsync(Admin.class) to group all beans related to admin functionality). GWT's code splitter will then put the code of all managed bean types with the same fragment name into the same code fragment (JavaScript file).

Error Detection for Common Pitfalls in Your IDE

By adding the following dependency to your project you will get automatic error detection for common Errai pitfalls directly in your IDE. While this covers an increasing amount of pitfalls, we are happy to accept your contributions. If you can think of more checks we should include please let us know or send us a pull request! Note that in Eclipse you will have to manually enable annotation processing: Go to Eclipse Workspace Preferences->Maven->Annotation Processing and select the "Automatically Configure JDT APT" radio button. In Eclipse you will also need to install the m2e-apt plugin.

That is all for today. Happy Coding!

What's new in Errai 3? Part 2: Role-Based Access Control and PicketLink Integration

This is the second post in a series describing new features in Errai 3.0. This article is about Errai Security, which provides role-based access control with optional PicketLink integration.

Errai Security provides a declarative way of securing pages, UI elements, and remote services. Below we'll show how it is used, and how you can use it with PicketLink or another server-side security framework of your choice.

@RestrictedAccess

Role-based access control in Errai Security is focused around the @RestrictedAccess annotation. Whether you're securing a @Page, @Remote interface or UI element, you simply annotate the secured resource with @RestrictedAccess.

The annotation takes an optional array of role names (Strings). For a user to be able to access a resource, they must have all of these roles; if they do not have all of the required roles, we say that the user is unauthorized. @RestrictedAccess without roles blocks access to those not logged-in; if a user is denied access because they are not logged-in, we say that they are unauthenticated.

Restricting @Page

Here is an Errai Navigation @Page that restricts access to users lacking the admin role:

When a user is denied access to this page, one of two things will happen:

• They will be redirected to the application's login page if unauthenticated.
• They will be redirected to the application's security error page if unauthorized.

You can define any Errai Navigation page as login page or security error page with the @Page annotation role attribute. For example, here is a class that functions as both a login and security error page:

Restricting @DataFields

In @Templated widgets, Errai Security can be used to apply CSS styles to template-bound fields (for example for hiding UI elements from unauthorized users).

When a user lacks permissions for one of the @DataFields above, the element in the template will have the CSS class, errai-restricted-access-style, applied. The CSS definitions ensure that the admin anchor will not be displayed to unauthorized users while the logout anchor will only be seen by unauthenticated users.

Restricting Remote Services

Errai Security can be used to secure Errai Bus RPCs, JAX-RS Endpoints, and Errai Messaging Services. When access to a service is denied, a UnauthenticatedException or UnauthorizedException is thrown on the server, which can be handled on the client with an ErrorCallback.

The default error handling provides behaviour similar to @RestrictedAccess on @Pages: unauthorized access causes navigation to the security error page and unauthenticated access causes navigation to the login page.

Errai Bus RPC

Errai JAX-RS Endpoint

Authentication and Server-Side Integration

The single point of contact between Errai Security and your preferred server-side security framework is the AuthenticationService. This interface is used to log in and out, and obtain an instance of the current User. The AuthenticationService is an @Remote interface, so you can use Errai RPC to call it from the client. errai-security-picketlink.jar provides a default AuthenticationService implementation using PicketLink. Using this implementation requires no configuration: just have the jar on your classpath and you're good to go.

Here is a login page that uses an AuthenticationService caller for logging in.

Using a Custom AuthenticationService

Integrating Errai Security with a different security back-end is as simple as implementing the AuthenticationService, and making your implementation a valid CDI bean. You can even implement your own User and Role types: for example, the Errai JPA Demo AuthenticationService uses a custom User implementation that is a JPA entity.

See It In Action

If you'd like to see Errai Security in action, you should checkout the Errai Security Demo. If you have any feedback, we'd love to hear it!

What's new in Errai 3? Part 1: RPC Enhancements

This is the first post in a series describing new features in Errai 3 that we haven't blogged about so far. We have recently published the first release candidate and plan to release 3.0.0.Final by the end of the month.

Today's focus is on enhancements made to Errai's RPC mechanism. You can find all details in our reference guide.

Global Exception Handlers

In your application you will likely find many remote procedure calls that potentially throw the same type of exception, usually related to some cross-cutting concern (i.e. authorization/authentication). Errai's new global exception handling feature supports handling these exceptions in a centralized way. It relieves you from having to provide error callbacks at each RPC invocation. Methods annotated with @UncaughtException are called when an exception occurs during a remote call that is not handled by an error callback. This feature is also used internally by Errai's new security module that we'll describe in detail in a future post.


Asynchronous handling of RPCs on the server

Sometimes computing the result of an RPC call can take a significant amount of time (i.e. because a slow database query needs to be executed or a third party service needs to be contacted). It then might be preferable to release the request-processing thread so it can perform other work and provide the RPC result from a different execution context farther in the future. Errai provides a special return type for this named CallableFuture which indicates to the RPC system that the result of the RPC will be provided asynchronously (after the remote method call has returned).

Here’s an example returning a future result of type String:

Enhancements to client-side remote call interceptors

In Errai 3, the new annotation @InterceptsRemoteCall can be used to define the interceptor target directly on the actual interceptor. This is useful in case you can't or don't want to annotate the remote interface with @InterceptedCall. Client-side interceptors can now also be IOC managed beans, which means you can now simply @Inject dependencies into it. Thanks to Eric Wittman for implementing these features!


Stay tuned for more new features in Errai 3 and as always, feedback is welcome and appreciated!

Errai 3.0.0.CR1 released!

The Errai team is proud to announce the availability of Errai 3.0.0.CR1. We have finished our series of milestone releases, completed and hardened all planned features and are now getting ready for the 3.0.0.Final release (planned for the end of May).

Errai 3.0.0.CR1 contains stable versions of the new Errai Security and Errai Mobile modules. Relative to the last milestone release, this release also brings improved code splitting support in Errai IOC, development mode performance improvements and an improved Errai Forge Addon.

Check out the release notes for a full list of fixes and improvements and watch this space for more details as we're moving towards 3.0.0.Final. Please upgrade your projects and help us test and harden Errai 3.

Our project roadmap can be found here. We're always looking for feedback!

Please join us on Freenode #errai, the errai-dev mailing list, or on our community forums.

Happy coding!

Have you taken Errai Data Sync for a spin yet?

Last June we released the first version of the Errai Data Sync module. It complements Errai JPA and provides functionality to automatically keep your local entities (persisted in local storage) in sync with the server. See the original blog post for details.

We have just added a new declarative, annotation-driven API that will make using Errai Data Sync even easier. Here's a short example:


When a user navigates to this page, either by browsing to #GroceryListView;activeUserId=1 or by transitioning from another page, a data sync worker will start to periodically synchronize the entities that match the query specified in the parameter to @Sync. This query parameter refers to a named query defined on an entity type: in this case GroceryList. The @SyncParams refer to fields of the enclosing managed bean to use them as query parameter values. In the example above we make use of the activeUserId field to only synchronize the grocery list of the currently active user.

The onDataSyncComplete method is invoked every time a synchronization cycle completes. It can be used to update the UI with the new data or to resolve conflicts. By default, conflicts are resolved in a favour of the server but you can change this behaviour (see the documentation for details).

We encourage you to try out Errai DataSync and are eager to get your feedback! What additional functionality would you like to see? Do you like the API or have changes to propose?

Please join us on Freenode #errai, the errai-dev mailing list, or on our community forums.