net.windward.xmlreport
Interface ProcessReportAPIBase

All Known Subinterfaces:

ProcessDocxAPI, ProcessExcelMLAPI, ProcessHtmlAPI, ProcessPdfAPI, ProcessReportAPI, ProcessRtfAPI, ProcessTxtAPI, ProcessWordMLAPI, ProcessXlsAPI, ProcessXlsxAPI

public interface ProcessReportAPIBase

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. This class exists seperate from ProcessReportAPI because of the .net version.

Version:

2.0 2 January 2004

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.
ProcessReportAPIBase	duplicate(java.io.OutputStream out) Creates and returns a copy of this object.
java.lang.String	getBaseDirectory() Get the base directory used for imported files that have a relative path.
int	getCharset() This call set's the locale used in creating a report.
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.
int	getReportType() Get the report format of the output stream.
java.lang.String	getSubject() Get the subject of the document.
java.lang.String	getTitle() Get the title of the document.
boolean	isDebugMode() Get if debug mode is on or off.
void	process() Create a report from the input (xml & rtf) streams, writing it to the output (report) stream.
void	processComplete() Process the final report and create the output.
void	processData(DataSourceProvider data, java.lang.String datasource) 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	setDebugMode(boolean debugOn) Set debug mode on or off.
void	setKeywords(java.lang.String keywords) 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 subject) Set the subject of the document.
void	setTitle(java.lang.String title) Set the title of the document.

Method Detail

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.

Parameters:

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

getCharset

public int getCharset()

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 the locale used for <wr:out>. This call allows you to force the locale the report is written in. The passed in value is the Windows country/language number (English (U.S.) is 0x0409). This has nothing to do with reading in the template, it only affects the output. The special constant LOCALE_DEFAULT will have the system use the template's locale.

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.

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.

Returns:

The locale used when generating areport.

getReportType

public int getReportType()

Get the report format of the output stream.

Returns:

The type (format) of the output report. Will be one of the TYP_* values.

setTitle

public void setTitle(java.lang.String title)

Set the title of the document. In html this will set both the TITLE tag and the title meta-tag.

Parameters:

title - The value of the title.

getTitle

public java.lang.String getTitle()

Get the title of the document. In html this will set both the TITLE tag and the title meta-tag.

Returns:

The value of the title.

setSubject

public void setSubject(java.lang.String subject)

Set the subject of the document. In html this will set the description meta-tag.

Parameters:

subject - The value of the subject.

getSubject

public java.lang.String getSubject()

Get the subject of the document. In html this will set the description meta-tag.

Returns:

The value of the subject.

setKeywords

public void setKeywords(java.lang.String keywords)

Set the keywords of the document. This are delimited by a ','. In html this will set the keywords meta-tag.

Parameters:

keywords - The value of the keywords.

getKeywords

public java.lang.String getKeywords()

Get the keywords of the document. They are delimited by a ','. In html this will set the keywords meta-tag.

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.

Parameters:

debugOn - Set to true to set debug mode on.

isDebugMode

public boolean isDebugMode()

Get if debug mode is on or off.

Returns:

The type true if debug mode is on.

setBaseDirectory

public void setBaseDirectory(java.lang.String directory)

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

Parameters:

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

getBaseDirectory

public java.lang.String getBaseDirectory()

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

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.

Returns:

The number of pages in the completed document.

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 (xml & rtf) 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, true);
processComplete();

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.

java.lang.IllegalArgumentException - thrown if come across an unknown element type or an illegal reportType value is used.

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()
                  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(rtfTemplate) or ProcessReport(rtfTemplate, report).

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.

java.lang.IllegalArgumentException - thrown if come across an unknown element type or an illegal reportType value is used.

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).

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.

addBean

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

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

Parameters:

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

bean - The bean to attach to that name.

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.

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.

processData

public void processData(DataSourceProvider data,
                        java.lang.String datasource)
                 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(rtfTemplate) or ProcessReport(rtfTemplate, report).

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.

datasource - 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.

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

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

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(rtfTemplate) or ProcessReport(rtfTemplate, report).

Throws:

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.

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

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().

Returns:

The report as a stream.

Throws:

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

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.

duplicate

public ProcessReportAPIBase duplicate(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:

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 called too often for the license type.