Saturday, December 19, 2020

OmniFaces 3.9 released with new exception handlers and resource handler

OmniFaces 3.9 has been released!

In this version, among others two new exception handlers have been added: the ExceptionSuppressor and ViewExpiredExceptionHandler, as well as a new resource handler: the VersionedResourceHandler. All based on contributions of Lenny Primak.

You can find the complete list of additions, changes and fixes at What's new in OmniFaces 3.9? list in showcase.

Installation

Non-Maven users: download OmniFaces 3.9 JAR and drop it in /WEB-INF/lib the usual way, replacing the older version if any.

Maven users: use <version>3.9</version>.

<dependency>
    <groupId>org.omnifaces</groupId>
    <artifactId>omnifaces</artifactId>
    <version>3.9</version>
</dependency>

If you're already on Jakarta EE 9 (e.g. GlassFish 6), then use 4.0-M4 instead. It's the Jakartified version of 3.9.

Suppressing inevitable exceptions

The ExceptionSuppressor allows you to completely suppress exceptions by simply refreshing the current page without leaving any trace in server logs. This is useful in case of inevitable exceptions such as those caused by an abruptly aborted network connection between client and server.

In order to install it, add it as last exception handler factory in faces-config.xml (because you don't want earlier registered exception handlers from possibly taking over the handling of the to-be-suppressed exceptions; the last registered one basically wraps the previous registered one and thus runs as the first):

<factory>
    ...
    ...
    <exception-handler-factory>org.omnifaces.exceptionhandler.ExceptionSuppressorFactory</exception-handler-factory>
</factory>

And configure the to-be-suppressed exceptions as a commaseparated string of fully qualified names of exception types in web.xml as the value of a context parameter with the name org.omnifaces.EXCEPTION_TYPES_TO_SUPPRESS:

<context-param>
    <param-name>org.omnifaces.EXCEPTION_TYPES_TO_SUPPRESS</param-name>
    <param-value>java.nio.channels.ClosedByInterruptException,java.nio.channels.IllegalSelectorException</param-value>
</context-param>

Suppressing view expired exceptions

The ViewExpiredExceptionHandler is a specialized subclass of ExceptionSuppressor which does basically the same but additionally sets a specific flash scoped attribute so that the view and/or the backing bean can consult whether the currently requested page was the consequence of a refresh after a ViewExpiredException.

In order to install it, add it as exception handler factory in faces-config.xml:

<factory>
    <exception-handler-factory>org.omnifaces.exceptionhandler.ViewExpiredExceptionHandlerFactory</exception-handler-factory>
</factory>

Noted should be that this is essentially a poor practice as this is very likely to cause bad user experience when the view was not expired as the consequence of an expired session. Although this is a rather rare case, if you want to properly deal with this condition, then better use a specific error page in web.xml which can be managed by FullAjaxExceptionHandler. From the error page on, you'll have more control over whether to actually refresh/redirect the request or not.

Adding cache bust query string to resources

The VersionedResourceHandler will automatically add version parameter with query string name v to all resource URLs with a value which can be obtained from a managed bean.

In order to install it, add it as last resource handler in faces-config.xml (because you don't want to disturb any other registered resource handlers which themselves already add a v query string parameter):

<application>
    ...
    ...
    <resource-handler>org.omnifaces.resourcehandler.VersionedResourceHandler</resource-handler>
</application>

The value of the version parameter can in turn be defined as the value of a web.xml context parameter with the name org.omnifaces.VERSIONED_RESOURCE_HANDLER_VERSION which in turn can represent an EL expression referring a managed bean property:

<context-param>
    <param-name>org.omnifaces.VERSIONED_RESOURCE_HANDLER_VERSION</param-name>
    <param-value>#{environment.version}</param-value>
</context-param>

How about OmniFaces 2.x and 1.1x?

The 2.x got the same bugfixes as 3.9 and has been released as 2.7.9. This version is for JSF 2.2 users with CDI. In case you've already migrated to JSF 2.3, use 3.x instead.

The 1.1x is basically already since 2.5 in maintenance mode. I.e. only critical bugfix versions will be released. It's currently still at 1.14.1 (May 2017), featuring the same features as OmniFaces 2.4, but without any JSF 2.2 and CDI things and therefore compatible with CDI-less JSF 2.0/2.1.

No comments: