net.windward.xmlreport
Class ProcessReport

java.lang.Object
  |
  +--net.windward.xmlreport.ProcessReport

All Implemented Interfaces:

ProcessReportAPI, ProcessReportAPIBase

Direct Known Subclasses:

ProcessDocx, ProcessExcelML, ProcessHtml, ProcessPdf, ProcessRtf, ProcessTxt, ProcessWordML, ProcessXls, ProcessXlsx

public abstract class ProcessReport

extends java.lang.Object

implements ProcessReportAPI

This class is the base class that takes a template stream and a DataSource and merges them to create a report stream. The way to use this is to construct an object that extends this class, set any options, then call the process methods.

There are two approaches to processing a rpeport. The first is to call: processSetup();
processData(xmlData, name); // can be called 0 - N times
processComplete();
The second approach is to call: process();
By definition the second method can only be called if the object constructor includes the xml file and there is only 1 xml file to be processed.

The calling method must close all streams after calling process(). process() will flush the output (report) stream before returning.

Version:

2.0 2 January 2004

Field Summary

static int	TEMPLATE_TYPE_DOCX The template is a Word 2007 DOCX file.
static int	TEMPLATE_TYPE_RTF The template is an RTF file.
static int	TEMPLATE_TYPE_UNKNOWN Parse the template to determine what format it is.
static int	TEMPLATE_TYPE_WORD_11 The template is a Word 2003 WordML XML file.
static int	TEMPLATE_TYPE_XLSX The template is an Excel 2007 XLSX file.

Fields inherited from interface net.windward.xmlreport.ProcessReportAPI

CHARSET_DEFAULT, CHARSET_RTF, CHARSET_UNICODE, LOCALE_DEFAULT, LOCALE_SYSTEM, TYP_DOCX, TYP_EXCEL_ML, TYP_HTML, TYP_PDF, TYP_RTF, TYP_TXT, TYP_WORD_ML, TYP_XLS, TYP_XLSX

Constructor Summary

ProcessReport(DataSourceProvider data, java.io.InputStream template, java.io.OutputStream report)
Create a ProcessReport object with the passed in template & data streams, writing it to the passed in report stream.

ProcessReport(java.io.InputStream templateStream)
Create a ProcessReport object with the passed in template.

ProcessReport(java.io.InputStream xmlData, java.io.InputStream templateStream, java.io.OutputStream report)
Create a ProcessReport object with the passed in template & data streams, writing it to the passed in report stream.

ProcessReport(java.io.InputStream templateStream, java.io.OutputStream report)
Create a ProcessReport object with the passed in template, writing it to the passed in report stream.

ProcessReport(ProcessReport src, java.io.OutputStream out)
Creates and returns a copy of this object.

Method Summary

void	addBean(java.lang.String name, BeanProvider bean) This adds a bean that is available during the processing of a report.
void	close() Call when you are done with this object, including done with the OutputStream returned by getReport if that stream was created by ProcessReport.
static void	dispose() Releases all resources held by Windward Reports.
java.lang.String	getBaseDirectory() Get the base directory used for imported files that have a relative path.
int	getCharset() Html and txt files are generated using a charset (rtf & pdf use unicode).
static net.windward.chart.ChartProvider	getChartProvider() Returns the chart provider used for this process.
static java.lang.String	getCompany() The company in the license licenseKey.
static IImportFile	getImportingProvider() Returns the importing provider used for the engine.
net.windward.xmlreport.TemplateInfo	getInfo() Returns all vars referenced in the template that are not defined in the template.
java.lang.String	getKeywords() Get the keywords of the document.
java.util.Locale	getLocale() This call returns the locale used in creating a report.
int	getNumPages() Returns how many pages long a report is.
java.io.OutputStream	getReport() Return the final report.
java.lang.String	getSubject() Get the subject of the document.
java.lang.String	getTitle() Get the title of the document.
static java.lang.String	getVersion() The version of Windward Reports.
static int	getVersionMajor() The major version number of Windward Reports.
static int	getVersionMinor() The minor version number of Windward Reports.
static int	getVersionRelease() The release version number of Windward Reports.
static void	init() This method should be called before any other code anywhere in Windward Reports.
boolean	isDebugMode() Get if debug mode is on or off.
void	process() Create a report from the input streams, writing it to the output (report) stream.
void	processComplete() Process the final report and create the output.
void	processData(DataSourceProvider datasourceProvider, java.lang.String datasourceName) Process a set of data for the report.
void	processSetup() Process the template and get the report ready to process data files.
void	processSetup(int inputType) Process the template and get the report ready to process data files.
void	setBaseDirectory(java.lang.String directory) Set the base directory used for imported files that have a relative path.
void	setCharset(int num) Html and txt files are generated using a charset (rtf & pdf use unicode).
void	setChartProvider(net.windward.chart.ChartProvider chartProvider) Returns the chart provider used for this process.
void	setDebugMode(boolean debugOn) Set debug mode on or off.
void	setKeywords(java.lang.String docKeywords) Set the keywords of the document.
void	setLocale(java.util.Locale locale) This call set's the locale used in creating a report.
void	setSubject(java.lang.String docSubject) Set the subject of the document.
void	setTitle(java.lang.String docTitle) Set the title of the document.
static void	statLine(java.lang.String msg)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface net.windward.xmlreport.ProcessReportAPIBase

duplicate, getReportType

Field Detail

TEMPLATE_TYPE_UNKNOWN

public static final int TEMPLATE_TYPE_UNKNOWN

Parse the template to determine what format it is.

TEMPLATE_TYPE_RTF

public static final int TEMPLATE_TYPE_RTF

The template is an RTF file.

TEMPLATE_TYPE_WORD_11

public static final int TEMPLATE_TYPE_WORD_11

The template is a Word 2003 WordML XML file.

TEMPLATE_TYPE_DOCX

public static final int TEMPLATE_TYPE_DOCX

The template is a Word 2007 DOCX file.

TEMPLATE_TYPE_XLSX

public static final int TEMPLATE_TYPE_XLSX

The template is an Excel 2007 XLSX file.

Constructor Detail

ProcessReport

public ProcessReport(java.io.InputStream templateStream)
              throws LicenseException,
                     SetupException

Create a ProcessReport object with the passed in template. Objects created with this constructor must call:
processSetup()
processData()
processComplete()
Objects created with this constructor cannot call process.

Do not pass in buffered streams if you have the option. ProcessReport wraps all streams in buffers, generally BufferedReader and BufferedWriter.

Parameters:

templateStream - The report template.

Throws:

LicenseException - thrown if the license licenseKey check fails. The message will list the license check that failed.

ProcessReport

public ProcessReport(java.io.InputStream templateStream,
                     java.io.OutputStream report)
              throws LicenseException,
                     SetupException

Create a ProcessReport object with the passed in template, writing it to the passed in report stream. The report will be in the format requested (rtf, pdf, html, or txt). Objects created with this constructor must call:
processSetup()
processData()
processComplete()
Objects created with this constructor cannot call process.

Do not pass in buffered streams if you have the option. ProcessReport wraps all streams in buffers, generally BufferedReader and BufferedWriter.

Parameters:

templateStream - The report template.

report - The stream to write the report to.

Throws:

LicenseException - thrown if the license licenseKey check fails. The message will list the license check that failed.

ProcessReport

public ProcessReport(java.io.InputStream xmlData,
                     java.io.InputStream templateStream,
                     java.io.OutputStream report)
              throws DataSourceException,
                     LicenseException,
                     SetupException

Create a ProcessReport object with the passed in template & data streams, writing it to the passed in report stream. The report will be in the format requested. Objects created with this constructor must call process() and cannot call processSetup, ProcessData, or processComplete.

Do not pass in buffered streams if you have the option. ProcessReport wraps all streams in buffers, generally BufferedReader and BufferedWriter.

Parameters:

xmlData - The xml data that will be placed into the report where there are xml elements.

templateStream - The report template.

report - The stream to write the report to.

Throws:

DataSourceException - thrown if there is a problem with the datasource.

LicenseException - thrown if the license licenseKey check fails. The message will list the license check that failed.

ProcessReport

public ProcessReport(DataSourceProvider data,
                     java.io.InputStream template,
                     java.io.OutputStream report)
              throws LicenseException,
                     SetupException

Create a ProcessReport object with the passed in template & data streams, writing it to the passed in report stream. The report will be in the format requested. Objects created with this constructor must call process() and cannot call processSetup, ProcessData, or processComplete.

Do not pass in buffered streams if you have the option. ProcessReport wraps all streams in buffers, generally BufferedReader and BufferedWriter.

Parameters:

data - The data that will be placed into the report where there are xml elements.

template - The report template.

report - The stream to write the report to.

Throws:

LicenseException - thrown if the license licenseKey check fails. The message will list the license check that failed.

ProcessReport

public ProcessReport(ProcessReport src,
                     java.io.OutputStream out)
              throws AlreadyProcessedException,
                     LicenseException,
                     SetupException

Creates and returns a copy of this object. You may call this before or after calling processData(). You may then call processData() on the created object. You must call this after calling processSetup() and before calling processComplete(). While this mostly does a deep copy, it does not do a deep copy of bean objects or image data.

Parameters:

src - The ProcessReport object to copy.

out - The stream to write the report to. If null will create a ByteArrayOutputStream.

Throws:

AlreadyProcessedException - thrown if call the process steps out of order or call ones other than data twice.

LicenseException - thrown if the license licenseKey check fails. The message will list the license check that failed.

Method Detail

getVersionMajor

public static int getVersionMajor()

The major version number of Windward Reports. Version numbers are in the form MAJOR.MINOR.RELEASE.

Returns:

The major version number.

getVersionMinor

public static int getVersionMinor()

The minor version number of Windward Reports. Version numbers are in the form MAJOR.MINOR.RELEASE.

Returns:

The minor version number.

getVersionRelease

public static int getVersionRelease()

The release version number of Windward Reports. Version numbers are in the form MAJOR.MINOR.RELEASE.

Returns:

The release version number.

getVersion

public static java.lang.String getVersion()

The version of Windward Reports. Version numbers are generally in the form "MAJOR.MINOR.RELEASE" or "MAJOR.MINOR.RELEASE beta".

Returns:

The version.

getCompany

public static java.lang.String getCompany()

The company in the license licenseKey.

Returns:

The company name.

dispose

public static void dispose()

Releases all resources held by Windward Reports. After calling this you cannot call any method in Windward Reports.

init

public static void init()
                 throws LicenseException,
                        SetupException

This method should be called before any other code anywhere in Windward Reports. It can be called repeated times with no bad effects. While it is not necessary to call this method, it is recommended as this will verify the license and initialize the system. Otherwise these steps happen when the first report object is created.

Throws:

LicenseException - thrown if the license licenseKey check fails. The message will list the license check that failed.

statLine

public static void statLine(java.lang.String msg)

setCharset

public void setCharset(int num)

Html and txt files are generated using a charset (rtf & pdf use unicode). Normally html files are generated using utf-8 (unicode) except for HTML_1 which uses the native charset. Txt files are normally generated using the native charset. The native charset is not the java native charset, it is the default charset set in the rtf template document. This call allows you to force to charset the report is written in. The passed in value is the Windows codepage (Western Europe is 1252). This has nothing to do with reading in the template, it only affects the charset the output report is written in. The special constants CHARSET_* allow you to set this to values other than a specific charset.

Specified by:

setCharset in interface ProcessReportAPIBase

Parameters:

num - The charset to use when generating an html or txt report.

getCharset

public int getCharset()

Html and txt files are generated using a charset (rtf & pdf use unicode). Normally html files are generated using utf-8 (unicode) except for HTML_1 which uses the native charset. Txt files are normally generated using the native charset. The native charset is not the java native charset, it is the default charset set in the rtf template document. This call allows you to force to charset the report is written in. The passed in value is the Windows codepage (Western Europe is 1252). This has nothing to do with reading in the template, it only affects the charset the output report is written in. The special constants CHARSET_* allow you to set this to values other than a specific charset.

Specified by:

getCharset in interface ProcessReportAPIBase

Returns:

The charset to use when generating an html or txt report.

setLocale

public void setLocale(java.util.Locale locale)

This call set's the locale used in creating a report. If not set, the default is not the system locale - it is the locale of the report template. This affects; 1) The output report locale for html and rtf reports, 2) The charset used for txt reports, 3) The rules used for soft line breaks (this mostly affects Thai), and 4) the locale used for <wr:out>.

The passed in value can be any locale or the values LOCALE_DEFAULT or LOCALE_SYSTEM. LOCALE_DEFAULT will use the locale in the report template. LOCALE_DEFAULT will use the system locale.

Specified by:

setLocale in interface ProcessReportAPIBase

Parameters:

locale - The locale to use when generating a report.

getLocale

public java.util.Locale getLocale()

This call returns the locale used in creating a report. This method should not be called until after the report template has been parsed.. This is used by; 1) The output report locale for html and rtf reports, 2) The charset used for txt reports, 3) The rules used for soft line breaks (this mostly affects Thai), and 4) the locale used for <wr:out>.

This will return null if set to LOCALE_DEFAULT until after the template has been parsed. Once the template has been parsed it will return the locale of the template in that case.

Specified by:

getLocale in interface ProcessReportAPIBase

Returns:

The locale used when generating areport.

setTitle

public void setTitle(java.lang.String docTitle)

Set the title of the document.

Specified by:

setTitle in interface ProcessReportAPIBase

Parameters:

docTitle - The value of the title.

getTitle

public java.lang.String getTitle()

Get the title of the document.

Specified by:

getTitle in interface ProcessReportAPIBase

Returns:

The value of the title.

setSubject

public void setSubject(java.lang.String docSubject)

Set the subject of the document.

Specified by:

setSubject in interface ProcessReportAPIBase

Parameters:

docSubject - The value of the subject.

getSubject

public java.lang.String getSubject()

Get the subject of the document.

Specified by:

getSubject in interface ProcessReportAPIBase

Returns:

The value of the subject.

setKeywords

public void setKeywords(java.lang.String docKeywords)

Set the keywords of the document. This are delimited by a ','.

Specified by:

setKeywords in interface ProcessReportAPIBase

Parameters:

docKeywords - The value of the keywords.

getKeywords

public java.lang.String getKeywords()

Get the keywords of the document. They are delimited by a ','.

Specified by:

getKeywords in interface ProcessReportAPIBase

Returns:

The value of the keywords.

setDebugMode

public void setDebugMode(boolean debugOn)

Set debug mode on or off. If debug mode is on, common user errors will be written to the report rather than throwing an exception.

Specified by:

setDebugMode in interface ProcessReportAPIBase

Parameters:

debugOn - Set to true to set debug mode on.

isDebugMode

public boolean isDebugMode()

Get if debug mode is on or off.

Specified by:

isDebugMode in interface ProcessReportAPIBase

Returns:

The type true if debug mode is on.

setBaseDirectory

public void setBaseDirectory(java.lang.String directory)

Description copied from interface: ProcessReportAPIBase

Set the base directory used for imported files that have a relative path.

Specified by:

setBaseDirectory in interface ProcessReportAPIBase

Following copied from interface: net.windward.xmlreport.ProcessReportAPIBase

Parameters:

directory - The base directory. Does not need to have a final /.

getBaseDirectory

public java.lang.String getBaseDirectory()

Description copied from interface: ProcessReportAPIBase

Get the base directory used for imported files that have a relative path.

Specified by:

getBaseDirectory in interface ProcessReportAPIBase

Following copied from interface: net.windward.xmlreport.ProcessReportAPIBase

Returns:

The base directory. Will always have a trailing /.

getNumPages

public int getNumPages()

Returns how many pages long a report is. Can only be called after process completes. For html and text reports (which by definition are 1 page long) it will return the number of pages it would be if it was an rtf or pdf report.

Specified by:

getNumPages in interface ProcessReportAPIBase

Returns:

The number of pages in the completed document.

processSetup

public void processSetup()
                  throws AlreadyProcessedException,
                         net.windward.format.TemplateParseException,
                         java.io.IOException,
                         TagException,
                         DataSourceException,
                         BeanProviderException,
                         LicenseException

Process the template and get the report ready to process data files. This should only be called once for a given ProcessReport object! This method can only be called by objects create with ProcessReport(template) or ProcessReport(template, report).

Specified by:

processSetup in interface ProcessReportAPIBase

Throws:

java.io.IOException - thrown if have problems accessing the xml, template, or report streams.

LicenseException - thrown if called too often for the license type.

TagException - thrown if there is an unmatched if/while - end. Not thrown in debug mode.

AlreadyProcessedException - thrown if call process multiple times on an object.

DataSourceException - thrown if there is a problem with the datasource.

processSetup

public void processSetup(int inputType)
                  throws AlreadyProcessedException,
                         net.windward.format.TemplateParseException,
                         java.io.IOException,
                         TagException,
                         DataSourceException,
                         BeanProviderException,
                         LicenseException

Process the template and get the report ready to process data files. This should only be called once for a given ProcessReport object! This method can only be called by objects create with ProcessReport(template) or ProcessReport(template, report).

Specified by:

processSetup in interface ProcessReportAPIBase

Parameters:

inputType - The format of the input template. Use one of the INPUT_FILE_TYPE_* integers.

Throws:

java.io.IOException - thrown if have problems accessing the xml, template, or report streams.

LicenseException - thrown if called too often for the license type.

TagException - thrown if there is an unmatched if/while - end. Not thrown in debug mode.

AlreadyProcessedException - thrown if call process multiple times on an object.

DataSourceException - thrown if there is a problem with the datasource.

getChartProvider

public static net.windward.chart.ChartProvider getChartProvider()

Returns the chart provider used for this process. The default is JFreeChartProvider. This is not part of the public API.

Returns:

The chart provider in use.

getImportingProvider

public static IImportFile getImportingProvider()

Returns the importing provider used for the engine. This is not part of the public API.

Returns:

The chart provider in use.

setChartProvider

public void setChartProvider(net.windward.chart.ChartProvider chartProvider)

Returns the chart provider used for this process. The default is JFreeChartProvider.

Specified by:

setChartProvider in interface ProcessReportAPI

Parameters:

chartProvider - The chart provider to use.

getInfo

public net.windward.xmlreport.TemplateInfo getInfo()
                                            throws java.io.IOException,
                                                   DataSourceException,
                                                   BeanProviderException,
                                                   TagException,
                                                   AlreadyProcessedException

Returns all vars referenced in the template that are not defined in the template. If there is a <wr:set var='name' value='3'/> that will not be in this list.

Specified by:

getInfo in interface ProcessReportAPIBase

Returns:

The names of all undefined vars.

Throws:

AlreadyProcessedException - thrown if setup not called or complete called.

java.io.IOException - thrown if have problems accessing the xml, template, or report streams.

TagException - thrown if there is an unmatched if/while - end. Not thrown in debug mode.

DataSourceException - thrown if there is a problem with the datasource.

addBean

public void addBean(java.lang.String name,
                    BeanProvider bean)

This adds a bean that is available during the processing of a report.

Specified by:

addBean in interface ProcessReportAPIBase

Parameters:

name - The name of the bean. This is the bean="name" attribute in the tag.

bean - The bean to attach to that name.

processData

public void processData(DataSourceProvider datasourceProvider,
                        java.lang.String datasourceName)
                 throws java.io.IOException,
                        TagException,
                        AlreadyProcessedException,
                        DataSourceException,
                        BeanProviderException

Process a set of data for the report. This method can be called multiple times - but only once for each datasource. This method can only be called by objects create with ProcessReport(template) or ProcessReport(template, report).

Do not pass in buffered streams if you have the option. ProcessReport wraps all streams in buffers, generally BufferedReader and BufferedWriter.

Specified by:

processData in interface ProcessReportAPIBase

Parameters:

datasourceProvider - The data that will be placed into the report where there are xml elements.

datasourceName - The name of the datasource to process. Only tags with this datasource will be processed. A value of "" is legitimate and signifies the default datasource.

Throws:

java.io.IOException - thrown if have problems accessing the xml, template, or report streams.

LicenseException - thrown if called too often for the license type.

TagException - thrown if there is an unmatched if/while - end. Not thrown in debug mode.

AlreadyProcessedException - thrown if call process multiple times on an object.

DataSourceException - thrown if there is a problem with the datasource.

processComplete

public void processComplete()
                     throws java.io.IOException,
                            TagException,
                            AlreadyProcessedException,
                            DataSourceException,
                            BeanProviderException,
                            LicenseException

Process the final report and create the output. This must be called after processData and before getReport. This should only be called once for a given ProcessReport object! This method can only be called by objects create with ProcessReport(template) or ProcessReport(template, report).

Specified by:

processComplete in interface ProcessReportAPIBase

Throws:

java.io.IOException - thrown if have problems accessing the xml, template, or report streams.

LicenseException - thrown if called too often for the license type.

TagException - thrown if there is an unmatched if/while - end. Not thrown in debug mode.

AlreadyProcessedException - thrown if call process multiple times on an object.

DataSourceException - thrown if there is a problem with the datasource.

getReport

public java.io.OutputStream getReport()
                               throws AlreadyProcessedException

Return the final report. In the case of the ProcessReport(template) constructor, this is gauranteed to be of type ByteArrayOutputStream. In the case of ProcessReport(xml, template, report) this is gauranteed to be the report variable passed in. This can only be called after process() or processData().

Specified by:

getReport in interface ProcessReportAPIBase

Returns:

The report as a stream.

process

public void process()
             throws LicenseException,
                    java.io.IOException,
                    net.windward.format.TemplateParseException,
                    java.lang.IllegalArgumentException,
                    TagException,
                    AlreadyProcessedException,
                    DataSourceException,
                    BeanProviderException

Create a report from the input streams, writing it to the output (report) stream. This should only be called once for a given ProcessReport object! This call is the equivilent of calling:
processSetup();
processData(xmlData, "");
processComplete();
This can only be called on objects that were created with ProcessReport(xmlData, template, report).

Specified by:

process in interface ProcessReportAPIBase

Throws:

java.io.IOException - thrown if have problems accessing the xml, template, or report streams.

LicenseException - thrown if called too often for the license type.

TagException - thrown if there is an unmatched if/while - end. Not thrown in debug mode.

AlreadyProcessedException - thrown if call process multiple times on an object.

DataSourceException - thrown if there is a problem with the datasource.

close

public void close()

Call when you are done with this object, including done with the OutputStream returned by getReport if that stream was created by ProcessReport.

Specified by:

close in interface ProcessReportAPIBase