Tipps & Tricks - Groovy Web-Error-Handler

Vorwort

In Intrexx können eigene Errorhandler definiert werden. Damit können auftretende Fehler in Prozessen oder Velocity-Skripts genauer spezifiziert und aussagekräftigere Fehlermeldungen für Benutzer bereit gestellt werden.

Errorhandler-Datei

Die benutzerdefinierten Errorhandler befinden sich im Portalverzeichnis "internal/system/vm/html/errorhandler/custom/". Eine Errorhandler-Datei muss folgenden Konventionen genügen:

  • Dateiname beginnt mit "handler_"

  • gefolgt von einer zweistelligen Zahl mit anschließendem Unterstrich

  • Dateiendung ".groovy"

Im Ordner befindet sich bereits eine Beispieldatei mit dem Namen "handler_50_xxx.groovy.example". Der Titel zwischen den Zahlen inkl. Unterstrich und der Dateiendung kann beliebig gewählt werden. Errorhandler werden lexikographisch sortiert und in dieser Reihenfolge abgearbeitet. Die Abarbeitung endet mit dem ersten Handler, der einen Titel sowie optional eine Beschreibung definiert. Es ist also sicherzustellen, dass vor dem Setzen eines Titels für die Fehlermeldung im Browser überprüft wird, ob es sich um einen Fehler handelt, der gesondert behandelt werden soll. Die Beispieldatei "handler_50_xxx.groovy.example" zeigt eine beispielhafte Implementierung: 

/*

	The variable g_exception contains the exception that indicates the error.

	Additional methods added to java.lang.Throwable:

	g_exception.getCauseOfType(SessionException)
	g_exception.getCauseOfType("de.uplanet.lucy.server.session.SessionException")

	g_exception.getCauseOfType(WorkflowException)
	g_exception.getCauseOfType("de.uplanet.lucy.server.workflow.WorkflowException")

	g_exception.isCausedBy(WorkflowException)
	g_exception.isCausedBy("de.uplanet.lucy.server.workflow.WorkflowException")

	g_exception.getRootCause()
	g_exception.isCausedByAccessControlException()
*/


// decide if we must handle the error or not
def bMyError = g_exception.isCausedBy(java.lang.Exception)

if (bMyError)
{
	switch (g_language)
	{
		case "de":
			title        = "Bitte Titel angeben"
			description  = "Bitte Beschreibung angeben. ${g_exception.message}"
			showEmbedded = false // equivalent to showBare = true
			break

		default:
			title       = "Please provide a title"
			description = "Please provide a description: ${g_exception.message}"
			showEmbedded = false // equivalent to showBare = true
			break
	}
}

Mit 

def bMyError = g_exception.isCausedBy(java.lang.Exception)

wird getestet, ob es sich bei der auslösenden Exception um eine Exception handelt, auf die benutzerdefiniert reagiert werden soll. Ist in diesem Fall die auslösende Exception vom Typ "java.lang.Exception", ist der Rückgabewert "bMyError" true. Somit ist die anschließende if-Bedingung erfüllt. In Abhängigkeit von der aktuellen Sprache wird die definierte Fehlermeldung im Browser angezeigt. Zur Definition der Fehlermeldung können folgende Eigenschaften gesetzt werden:

Eigenschaft

Beschreibung

title

Text der Titelzeile in der Browser-Fehlermeldung

description

Beschreibungstext in der Browser-Fehlermeldung

showEmbedded

Durch die Angabe von "true" oder "false" kann gesteuert werden, ob der eigentlichen Fehlermeldung ein weiteres Hinweisfenster vorgelagert wird.



Bei "true" wird das Hinweisfenster und erst mit Klick auf "Weitere Informationen" die benutzerdefinierte Fehlerbox angezeigt.

Die definierten Eigenschaften "title" und "description" werden im Fehlerfall im Browser angezeigt: Die über die lexikographische Ordnung festgelegte Abarbeitungsreihenfolge würde somit an dieser Stelle nach der Anzeige der Fehlermeldung abgebrochen werden.

Errorhandler im Einsatz

Exception-Analyse

Um das Auffinden einer Exception in einem Stacktrace bzw. die Suche nach der auslösenden Exception zu erleichtern, existieren über das Objekt "g_exception" Methoden, die das Error-Objekt analysieren und entsprechende Ergebnisse zurückliefern. 

g_exception.getCauseOfType(Class)
g_exception.getCauseOfType(String)

Im vorliegenden Error-Objekt wird nach dem ersten Vorkommen der übergebenen Exception gesucht. Ist die Suche erfolgreich, wird die Ursache zurückgeliefert, ansonsten null. Der zu suchende Fehlertyp kann als Class-Objekt oder als String mit einem voll qualifizierten Klassennamen übergeben werden. Beispiel: 

g_exception.getCauseOfType("java.io.FileNotFoundException")
g_exception.getRootCause()

Liefert die ursprünglich zugrunde liegende Exception zurück. 

g_exception.isCausedBy(Class)
g_exception.isCausedBy(String)

Hiermit kann überprüft werden, ob die vorliegende Exception vom Typ der übergebenen Exception ist. Liefert true zurück, wenn die Typen übereinstimmen, ansonsten false. Beispiel: 

def bIsError = g_exception.isCausedBy("java.io.FileNotFoundException")
g_exception.isCausedByAccessControlException()

Überprüft, ob eine Exception aufgetreten ist, die ihre Ursache in einer fehlenden Zugriffserlaubnis hat (z.B. Datengruppenrechte usw.). Liefert "true" zurück, wenn dies der Fall sein sollte, ansonsten "false". Beispiel: 

def bNoPermission = g_exception.isCausedByAccessControlException()

Beachten Sie, dass bei allen hier aufgeführten Methoden die Objekthierarchien und die Vererbung berücksichtigt werden. So beinhaltet beispielsweise der Test auf eine java.io.Exception auch den Test auf java.io.FileNotFoundException.

Exceptions kontextbezogen verarbeiten

In den bisherigen Beispielen wurden Exceptions lediglich im Allgemeinen überprüft. Da jedoch derselbe Exceptiontyp in unterschiedlichen Prozessen oder Applikationen auftreten kann und je nach Kontext differenziert betrachtet werden können soll, muss eine Möglichkeit gegeben sein, diesen Kontextbezug herzustellen. Um solche Unterscheidungen zu realisieren, existieren diverse Möglichkeiten. Eine besteht darin, Exceptions immer mit einer kontextbezogenen Fehlermeldung zu versehen. Somit besteht innerhalb des Errorhandlers die Möglichkeit, nochmals auf die Fehlermeldung zu filtern und erst bei erfolgreicher Filterung die benutzerdefinierte Abarbeitung zu starten. Als Anregung seien hier z.B. spezielle Fehlercodes, applikations-bezogene Kürzel oder Ähnliches genannt. Beispiel: 

throw new FileNotFoundException("PROJ_VERW_001")

Somit ist die Fehlermeldung mit einem kontextbezogenen Kürzel gekennzeichnet und kann anschließend entsprechend vorselektiert werden: 

if (g_exception.isCausedBy(java.io.FileNotFoundException))
{
    def rootCause = g_exception.getRootCause()

    if (rootCause.message != null && 
        rootCause.message.contains("PROJ_VERW_001"))
        bMyError = true
    else
        bMyError = false
}

if (bMyError)
{
    switch (g_language)
    {
//...
        case "de":
            title        = "Projektverwaltung Fehler 001"
            description  = "Pflichtenheft-Datei wurde nicht gefunden."
            showEmbedded = false
            break
//...
    }
}

Durch die beiden if-Abfragen 

if (g_exception.isCausedBy(java.io.FileNotFoundException))

und 

if (rootCause.message != null && 
    rootCause.message.contains("PROJ_VERW_001"))

wird der benutzerdefinierte Errorhandler nur dann angesprochen und verwendet, wenn es sich um eine FileNotFoundException handelt und darüber hinaus das Kürzel "PROJ_VERW_001" vorhanden ist. Andere Exceptions dieses Typs ohne Kürzel werden nicht gesondert behandelt. Als Alternative zur Vergabe applikationsbezogener Kürzel kann mit Hilfe von Session- und / oder Requestwerten oder auch SharedState-Variablen gearbeitet und somit eine kontextbezogene Verarbeitung realisiert werden. Im folgenden Beispiel wird eine Exception nur dann gesondert behandelt, wenn sich ein Benutzer innerhalb einer bestimmten Applikation befindet. Erreicht wird diese Selektion über die Abfrage der Requestvariable "rq_AppGuid". 

def bMyError = false

if (g_exception.isCausedBy(java.io.IOException) && 
    g_request["rq_AppGuid"] == "93BDFE88ADC4BAAB66630548C61B8ADD6F287AA6")
    bMyError = true

if (bMyError)
{
    switch (g_language)
    {
...
        case "de":
            title        = "Projektverwaltung"
            description  = """Es ist ein Fehler in der Applikation Projektverwaltung aufgetreten."""
            showEmbedded = false
            break
...
    }
}