Errai: The browser as a platform

Wednesday, August 13, 2014

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!

Monday, June 2, 2014

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!

Wednesday, May 21, 2014

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!

Thursday, May 8, 2014

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.


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!

Thursday, May 1, 2014

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!