Any complex Java system are subject to the occurrences of exceptions. From missed assignments which cause NullPointerExceptions to network issues which cause SQLExceptions be thrown, the unexpected happens—even in Rice applications.

Because of this, Rice builds on top of Struts’ exception mechanism to provide an easy way for exceptions to be handled and for incidents to be reported to the proper maintenance group.

When a developer creates a Rice application, there should be several struts-config.xml files created. The developer’s own struts-config.xml, of course, exists in {project_root}/src/main/webapp/WEB-INF. It will automatically be created with the following entry:

<global-exceptions>
    <exception type="java.lang.Throwable"
 handler="org.kuali.rice.kns.web.struts.pojo.StrutsExceptionIncidentHandler"
 key="meaningless" />
</global-exceptions>

This tells Struts that if any exceptions—or even Errors for that matter!—reach the Struts request processor, then it is to redirect the application to the org.kuali.rice.kns.web.struts.pojo.StrutsExceptionIncidentHandler. This handler, in turn, redirects to the following forward:

<action path="/kualiExceptionIncidentReport"
 type="org.kuali.rice.kns.web.struts.action.KualiExceptionHandlerAction">
    <forward name="basic" path="/kr/kualiExceptionIncidentReport.do" />
</action>

This forward does a number of things. First, it sends the exception to org.kuali.rice.kns.service.KualiExceptionIncidentService#getExceptionIncident to wrap the exception, and then reports the wrapped exception to org.kuali.rice.kns.service.KualiExceptionIncidentService#report.

In the default implementation, org.kuali.rice.kns.service.KualiExceptionIncidentService#report emails the mailing list specified in the KualiExceptionIncidentServiceImpl.REPORT_MAIL_LIST configuration parameter. The rest of the mail can be configured by overriding the service bean’s message template:

<bean id="knsExceptionIncidentService" class="org.kuali.rice.kns.service.impl.KualiExceptionIncidentServiceImpl">
    <property name="mailService"><ref bean="mailService"/></property>
    <property name="messageTemplate">
        <bean class="org.kuali.rice.kns.mail.MailMessage">
            <!-- The property place holder below must be specified in common-config-default.xml or any other KNS configuration file -->
            <property name="fromAddress">
                <value>${kr.incident.mailing.list}</value>
            </property>
        </bean>
    </property>
</bean>

Then the action redirects the user to the error page. In production environments, this page simply notes that an error occurred and that it had been reported to the system’s administrators. Helpfully, it also provides a text box so the user can describe the steps leading up to the incident. In development environments, this page also displays the top stack trace of the exception which occurred.

With this reporting mechanism, incidents are properly reported and can be responded to and fixed.