Module org.omnifaces
Package org.omnifaces.component.script

Class ScriptErrorHandler

java.lang.Object
jakarta.faces.component.UIComponent
jakarta.faces.component.UIComponentBase
org.omnifaces.component.script.ScriptFamily
org.omnifaces.component.script.ScriptErrorHandler
All Implemented Interfaces:
PartialStateHolder, StateHolder, TransientStateHolder, ComponentSystemEventListener, FacesListener, SystemEventListenerHolder, EventListener
public class ScriptErrorHandler extends ScriptFamily

The <o:scriptErrorHandler> is a component that catches uncaught JavaScript errors and unhandled promise rejections on the client and sends them to the server via navigator.sendBeacon(), where they are fired as ScriptError CDI events. This allows server-side logging of client-side JavaScript errors without any additional endpoint boilerplate.

Usage (client)

Just put the component in the <h:head> of the master template. It will automatically move itself to head even when placed elsewhere, but placing it in <h:head> makes the intent explicit. 

 <h:head>
     <o:scriptErrorHandler />
 </h:head>

This will register window.onerror and unhandledrejection event listeners which report any uncaught client-side errors to the server. You can optionally specify a CSS selector via ignoreSelector to suppress error reporting when a matching element exists in the document (e.g. on error pages where errors are expected). 

 <o:scriptErrorHandler ignoreSelector="body.errorPage" />

Usage (server)

Create a CDI bean (typically application scoped) that observes the ScriptError event. 

 @ApplicationScoped
 public class ScriptErrorObserver {

     private static final Logger logger = Logger.getLogger(ScriptErrorObserver.class.getName());

     public void onScriptError(@Observes ScriptError error) {
         logger.warning(error.toString());
     }
 }

The ScriptError event provides the following information:

Deduplication

To prevent flooding the server with repeated errors (e.g. from a requestAnimationFrame loop), the client-side script deduplicates errors by message, source URL, and line number. The deduplication queue size and expiry time can be configured via the maxRecentErrors and errorExpiry attributes, which default to 100 and 1 minute respectively.

Since:
5.2
Author:
Bauke Scholtz
See Also:

  • Field Details

    • COMPONENT_TYPE

      public static final String COMPONENT_TYPE
      The component type, which is "org.omnifaces.component.script.ScriptErrorHandler".
      See Also:

  • Constructor Details

    • ScriptErrorHandler

      public ScriptErrorHandler()

  • Method Details

    • processEvent

      public void processEvent(ComponentSystemEvent event)
      Move this component to head, so that error handlers are registered as early as possible.
      Specified by:
      processEvent in interface ComponentSystemEventListener
      Overrides:
      processEvent in class UIComponent
      Throws:
      IllegalArgumentException - When the ScriptErrorServlet is not registered because no CDI observer for ScriptError was found.

    • encodeChildren

      public void encodeChildren(FacesContext context) throws IOException
      Render the initialization script.
      Overrides:
      encodeChildren in class UIComponentBase
      Throws:
      IOException

    • getIgnoreSelector

      public String getIgnoreSelector()
      Returns the CSS selector for elements whose presence suppresses error reporting. When an element matching this selector exists in the document, errors will not be sent to the server. For example, body.errorPage to suppress reporting on error pages having <h:body styleClass="errorPage">.
      Returns:
      The CSS selector, or null.

    • setIgnoreSelector

      public void setIgnoreSelector(String ignoreSelector)
      Sets the CSS selector for elements whose presence suppresses error reporting. When an element matching this selector exists in the document, errors will not be sent to the server.
      Parameters:
      ignoreSelector - The CSS selector.

    • getMaxRecentErrors

      public int getMaxRecentErrors()
      Returns the maximum number of recent errors to keep for deduplication. Defaults to 100.
      Returns:
      The maximum number of recent errors.

    • setMaxRecentErrors

      public void setMaxRecentErrors(int maxRecentErrors)
      Sets the maximum number of recent errors to keep for deduplication. Defaults to 100.
      Parameters:
      maxRecentErrors - The maximum number of recent errors.

    • getErrorExpiry

      public int getErrorExpiry()
      Returns the time in milliseconds after which a recent error entry expires. Defaults to 60000 (1 minute).
      Returns:
      The error expiry time in milliseconds.

    • setErrorExpiry

      public void setErrorExpiry(int errorExpiry)
      Sets the time in milliseconds after which a recent error entry expires for deduplication. Defaults to 60000 (1 minute).
      Parameters:
      errorExpiry - The error expiry time in milliseconds.

    • registerServletIfNecessary

      public static void registerServletIfNecessary(ServletContext servletContext)
      Register the script error handler servlet if it has not already been registered and there is at least one CDI observer for ScriptError.
      Parameters:
      servletContext - The involved servlet context.