Windward DocumentationJava Report Engine User Manual FAQsHow Do I Enable Error Handling in Java Report Engine?

How Do I Enable Error Handling in Java Report Engine?

The Java Report Engine API includes a facility for collecting and displaying warnings and errors that occur while it is generating output. This article describes what the verify and error handling features do, with some examples of the warnings and errors they capture.  

This article also describes the API calls used to enable error handling, and provides example code based on one of our Catapult Java example command-line applications.

The relevant API calls are setTrackErrors() and GetErrorInfo().

What Does It Do?

The verify feature provides you with actionable information on non-fatal errors, warnings, and other issues contained within a Report Template that occur when generating output with Java Report Engine.

Error handling is a Tag property that can be set to catch errors and exceptions that occur in a Tag's query. Depending on the error-handling Tag property setting, otherwise fatal errors can be captured and ignored so output can be completed despite the error. For more details about the error-handling Tag property, see the Out Tag Reference.

Example Warnings and Errors

Here are some examples of the warnings and errors captured when the verify and error handling features are used:

Data Type Issues

warning: ‘Buchanan’ is String while NUMBER expected: <wr:out select=’SELECT dbo.Emplayees.LastName FROM dbo.Employees’ type=’NUMBER’ nickname='TypeError’ error-handling=‘Ignore type error;lgnore formatting error;Ignore select error;Node must exist’ datasource=’MSSQL’/>

warning: ‘Buchanan’ is String while NUMBER expected: <wrout select=’SELECT dbo.Emplayees.LastName FROM dbo.Employees’ type=‘NUMBER’ nickname='TypeError’ error-handling=‘Ignore type error;lgnore formatting error;Ignore select error;Node must exist’ datasource=’MSSQL’/>

Formatting Issues

warning: format(Buchanan, ) is not allowed: <wr:out select=’SELECT dbo.Employees.LastName FROM dbo.Employees’ type=‘NUMBER' nickname=TypeError’ error-handling= Ignore type error;Ignore formatting error;Iqnore select error;Node must exist’ datasource=’MSSQL’/>

warning: Could not parse: Adam: <wr:out select='/Formats-to-test/Author/Firstname’ type=‘DATE’ format=‘categary-date-type:0-format:m/d/yyyy’; nickname=’FORMAT_PROBLEM' error-handling=‘Ignore formatting error;Ignore select error’ datasource='TestingDatabase'/>

warning: format(Buchanan, ) is not allowed: <wr:out select=’SELECT dbo.Employees.LastName FROM dbo.Employees’ type=’NUMBER’ nickname=’TypeError’ error-handling=’Ignore type error;Ignore formatting error;Iqnore select error,Node must exist’ datasource=’MSSQL’/>

warning: Could not parse: Adam: <wr:out select='/Formats-to-test/Author/Firstname’ type=‘DATE’ format=‘categary-date-type:0-format:m/d/yyyy’; nickname=’FORMAT_PROBLEM' error-handling=‘Ignore formatting error;Ignore select error’ datasource='TestingDatabase'/>

Bad Select Statement

warning: Invalid column name ‘dbo’. Final select: select dbo from dbo.Employees: <wr:out select=‘select dbo from dbo.Employees’ nickname=‘DNE1' error-handling=’Ignore select error’ datasource=‘MSSQL’/>

warning: Invalid column name ‘dbo’. Final select: select dbo from dbo.Employees: <wr:out select=‘select dbo from dbo.Employees’ nickname=‘DNE1' error-handling=’Ignore select error’ datasource=‘MSSQL’/>

Node Does Not Exist

error: The tag returned no nodes: <wr:out select='/Formats-to-test/Nada’ nickname=‘Nadal' error-handling='Node must exist’ datasource=’TestingDatabase’/>

error: The tag returned no nodes: <wr:out select='/Formats-to-test/Nada’ nickname=‘Nadal' error-handling='Node must exist’ datasource=TestingDatabase’/>

Node Is Null

warning: The tag is empty: <wr:out select=‘select ShipRegion from dbo.Orders where OrderID=10248’ nickname=‘[ShipRegion]’ error-handling=‘Node must not return NULL’ datasource=‘MSSQL’/>

warning: The tag is empty: <wr:out select=‘select ShipRegion from dbo.Orders where OrderID=10248’ nickname=‘[ShipRegion]’ error-handling=‘Node must not return NULL’ datasource=‘MSSQL’/>

Verification Issues

warning: Tag uses undefined data source ‘OData’: <wr:set select=‘Employees?$select=Nada&amp;$top=1' var='varName3’ nickname=‘DNE8' error-handling=‘Ignore select error’ datasource='OData’/>

warning: Tag uses undefined data source ‘OData’: <wr:set select=‘Employees?$select=Nada&amp;$top=1' var='varName3’ nickname=‘DNE' error-handling=‘Ignore select error’ datasource='OData'/>

setTrackErrors()

setTrackErrors() is used to enable error handling in your Java Report Engine application: 

/**
* Enable or disable the error handling and verify features. If they are enabled you can call getErrorInfo() to
* get a list of errors encounterred during the report generation.
* By default these features are turned off (disabled).
*
* @param flag A combination of ERROR_HANDLING_ bits.
*/
void setTrackErrors(int flag);

setTrackErrors() is a member of the net.windward.xmlreport.errorhandling.ErrorInfo class.

setTrackErrors() Flags

Here are the values to which the setTrackErrors() flag argument can be set:

/**
* Handle errors as indicated by a tag properties.
*/
int ERROR_HANDLING_TRACK_ERRORS = 0x01;

/**
* Perform verification during a report generation.
*/
int ERROR_HANDLING_VERIFY = 0x02;

/**
* The bitmask that turns the complete error handling functionality off.
*/
int ERROR_HANDLING_NONE = 0x00;

/**
* The bitmask that turns the complete error handling functionality on.
*/
int ERROR_HANDLING_ALL = 0x03;

getErrorInfo()

getErrorInfo() is used to process any warnings and errors that occur while Java Report Engine is running, after setTrackErrors() is used to turn on error handling:

 

/**
* Get an object containing a set of errors encountered during the report generation. To enable the errors tracking
* you have to turn this feature on by a call to setTrackErrors().
*
* @return An instance of the ErrorInfo implementation.
*/
ErrorInfo getErrorInfo();

 

getErrorInfo() is also a member of the net.windward.xmlreport.errorhandling.ErrorInfo class.

Here is the ErrorInfo implementation:

/**
* A contract on the error information returning by the engine.
*/
public interface ErrorInfo {
/**
* Return true if a report generation produced any errors.
*
* @return True if there were errors during a report generation.
*/
boolean hasErrors();


/**
* Get a list of errors produced during a report generation. Each list item may represent an error of a warning.
*
* @return A list of errors.
*/
List<Issue> getErrors();
}

BasicXml.java Example

Here is the source file BasicXml.java from our Catapult Java command-line examples, with error handling added and NEW COMMENTS IN ALL CAPS:

/*
 * Copyright (c) 2012 by Windward Studios, Inc. All rights reserved.
 *
 * This program can be copied or used in any manner desired.
 */

import java.io.*;
import net.windward.datasource.DataSourceProvider;
import net.windward.datasource.xml.SaxonDataSource;
import net.windward.xmlreport.ProcessPdf;
import net.windward.xmlreport.ProcessReportAPI;
import net.windward.env.SystemWrapper;
import net.windward.xmlreport.errorhandling.ErrorInfo; // USED FOR ERROR HANDLING
import net.windward.xmlreport.errorhandling.Issue; // USED FOR ERROR HANDLING

/*
 * A sample usage of the Windward Java Engine. This is the first building block to a great report!
 *
 * This sample takes in a datasource and template file--in this case, data.xml and template.docx from
 * the data directory--and produces the report, stored as report.pdf in the out directory.
 *
 * Take a look, the results are amazing!
 */

public class BasicXml {
    public static void main(String[] args) {
        try {
        // To generate a report, first we need a ProcessReport object.  For now, we're using the
        // pdf format to output.

        File fileReport = new File("out/report.pdf");
        FileInputStream template = new FileInputStream("data/template.docx");
        FileOutputStream reportStream = new FileOutputStream(fileReport);
        ProcessReportAPI report = new ProcessPdf(template, reportStream);

        // TURN ON ERROR HANDLING
        report.setTrackErrors(ProcessReportAPI.ERROR_HANDLING_ALL);

        // Preparation...
        report.processSetup();

        // Set up the datasource. The parameters are connector package, url, username, password.
        // For each type of datasource, the connector package is different

        DataSourceProvider datasource = new SaxonDataSource(new FileInputStream("data/data.xml"));

        // Finally, send it to Windward for processing.  The second parameter is the name of the
        // datasource.  This should match the name used in your template.

        report.processData(datasource, "Orders");
        
        // And... DONE!
        report.processComplete();

        // PROCESS ANY ERRORS
        ErrorInfo errors = report.getErrorInfo();
        if (errors.hasErrors()) {
        for (Issue issue : errors.getErrors())
            System.out.println(issue.getMessage());
        }

        template.close();
        reportStream.close();
        System.out.println("Launching report " + fileReport.getAbsolutePath());
        SystemWrapper.LaunchFile(fileReport.getAbsolutePath());

        } catch (Exception e) {
            // Uh oh, just in case
            e.printStackTrace();
        }
    }
}

0 Comments

Add your comment

E-Mail me when someone replies to this comment