Package com.inet.report

Class Engine

java.lang.Object

com.inet.report.Engine

All Implemented Interfaces:

NodeParser, ReportGenerator, Serializable

public class Engine
extends Object
implements Serializable, NodeParser, ReportGenerator

This is the i-net Clear Reports report engine. Its purpose is to transform a report template and its associated data. The result can either be binary data to be viewed/printed by the viewer or it can be exported into a lot of export formats, like: HTML, PDF, PS, RTF, XLSX, XML, ....

The engine reads the report file and creates an array of output data that can be used by the client (java viewer or CSV, HTML, PDF, RTF, XLSX, XML, PS viewer, ...). The output data can be created by executing the following steps:

• Create a new engine by calling engine = new Engine(Engine.NO_EXPORT).
  To create a PDF render engine for example, use engine = new Engine(Engine.EXPORT_PDF).
• Set the path to the report template by calling engine.setReportFile("file:c:/report1.rpt") on windows or engine.setReportFile("/usr/share/clearreports/report1.rpt") on unix.
• Change the parameters of the report.
  For example if the report was created using ODBC to an Oracle database and you want to use a native driver (e.g. i-net SERO) instead to connect to a Oracle database, copy the file Sero.jar into the class path of i-net Clear Reports and set the name of the Data Source Configuration that should be used instead:
  

  
     DatabaseTables dbTables = engine.getDatabaseTables();
     Datasource ds = dbTables.getDatasource(0);
     ds.setDataSourceConfigurationName("Oracle_DataSourceConfiguration");
    

  Also, you could change the selection formula and examine or change other parts of the report template using RDC if you wish.
• Execute the report.
  Executing a report means transforming the report template together with the data from the database (or with the data that you have set using the method engine.setData()) into the target format (PDF, RTF, HTML, binary, ...).
• The last action would be to call the method engine.getPageData(int) which returns the requested report page.
• A report which has been executed can not be used further, you can not use neither engine.setReportFile() nor all other set or get methods other then the getPage*() methods on an executed report.

Note that the above command sequence will usually be located in a callback, for example in the checkProperties(Engine e, Properties p) callback of the ReportServlet or the ReportSocket. The callback will always be invoked when the viewer requests data from you.
In general you do not have to use the methods of this class directly. If you use the ReportServlet or the ReportSocket (Report Server), then you use a report URL instead which the ReportServlet and the ReportSocket parses and automatically calls the necessary setter methods for you. For example if you specify the URL http://localhost:9000/?report=file:c:/report1.rpt&datasource=Oracle_DataSourceConfiguration then the ReportSocket will automatically invoke the above code sequence.

However, you can use one of the checkProperties() callbacks to change the parameters before the above set methods are called (for example if you want to set or change the password).

If you want to use RDC, you can use the checkProperties(Engine e, Properties p) callback to examine and change the fields of the engine before the engine will execute the report.

See Also:

• Serialized Form

Field Summary

Fields

Modifier and Type	Field	Description
static final String	AREA_TYPE_DETAIL	Constant for getArea(String): Detail Area
static final String	AREA_TYPE_GROUP_FOOTER_PREFIX	Constant for getArea(String): Group Footer Prefix: To access a Group Footer, use this prefix in front of the 1-based group index you wish to access.
static final String	AREA_TYPE_GROUP_HEADER_PREFIX	Constant for getArea(String): Group Header Prefix: To access a Group Header, use this prefix in front of the 1-based group index you wish to access.
static final String	AREA_TYPE_PAGE_FOOTER	Constant for getArea(String): Page Footer
static final String	AREA_TYPE_PAGE_HEADER	Constant for getArea(String): Page Header
static final String	AREA_TYPE_REPORT_FOOTER	Constant for getArea(String): Report Footer
static final String	AREA_TYPE_REPORT_HEADER	Constant for getArea(String): Report Header
static final int	DETAILS	The constant for the index number of the details area.
static final String	EXPORT_BMP	Engine creates BMP output.
static final String	EXPORT_CSV	Engine creates CSV output. The column delimiter can be specified with property: delimiter.
static final String	EXPORT_DATA	Engine creates data output.
static final String	EXPORT_DOCX	Engine creates DOCX output.
static final String	EXPORT_EMAIL	Engine creates a simplified HTML output which can be used for emails.
static final String	EXPORT_GIF	Engine creates GIF output.
static final String	EXPORT_HTML	Engine creates HTML output.
static final String	EXPORT_HTML_ZIP	Engine creates HTML output.
static final String	EXPORT_JPEG	FOR INTERNAL USE ONLY
static final String	EXPORT_JPG	Engine creates JPG output.
static final String	EXPORT_JRA	FOR INTERNAL USE ONLY
static final String	EXPORT_JSON	Engine creates JSON output.
static final String	EXPORT_ODS	Engine creates OpenOffice ODS output.
static final String	EXPORT_PDF	Engine creates PDF output.
static final String	EXPORT_PNG	Engine creates PNG output.
static final String	EXPORT_PS	Engine creates postscript output.
static final String	EXPORT_PS2	Engine creates postscript 2 output.
static final String	EXPORT_PS3	Engine creates postscript 3 output.
static final String	EXPORT_RTF	Engine creates RTF output.
static final String	EXPORT_SVG	Engine creates SVG output.
static final String	EXPORT_TXT	Engine creates plain text output.
static final String	EXPORT_XLS	Engine creates XLS output.
static final String	EXPORT_XLSX	Engine creates XLSX output.
static final String	EXPORT_XML	Engine creates XML output.
static final int	LOG_DEBUG	Useful if you want to send bug reports to the i-net Clear Reports support at ClearReports@inetsoftware.de
static final int	LOG_ERROR	Log include error messages such as "report file could not be read, rendering aborted".
static final int	LOG_INFO	Log include information messages such as the JDBC driver that i-net Clear Reports uses.
static final int	LOG_STATUS	Log nothing except a status line for each rendered report.
static final int	LOG_WARN	Log include warning messages such as "font not found, using a replacement font"
static final String	NO_EXPORT	No export, use java viewer.
static final int	PAGE_FOOTER	The constant for the index number of the report header area.
static final int	PAGE_HEADER	The constant for the index number of the page header area.
static final int	REPORT_FOOTER	The constant for the index number of the report footer area.
static final int	REPORT_HEADER	The constant for the index number of the report header area.
protected int	rowCount	FOR INTERNAL USE ONLY

Constructor Summary

Constructors

Constructor	Description
Engine(String export_fmt)	Constructor creates an Engine for different file output formats.

Method Summary

Modifier and Type	Method	Description
void	addClippingListener(ClippingListener listener)	Registers a clipping listener with the engine - any time an element is clipped while rendering, this listener's method "clippingOnElement" is called
void	addFinishListener(EngineFinishListener listener)	Add a EngineFinishListener to this engine.
Group	addGroup(Field groupField)	Adds a newly created grouping into the grouping set and returns it.
void	execute()	Executes the report and stores the result data in an internal cache.
Area	getArea(int idx)	Returns an AreaElement of the Area set.
Area	getArea(String item)	Returns an area element of the set of areas.
int	getAreaCount()	Returns the number of Areas of the report.
int	getCacheSize()	This function returns the current cache size.
static String	getCreator()	Returns the creator string that i-net Clear Reports writes into the exported files.
DatabaseTables	getDatabaseTables()	Returns the DatabaseTables object for this report.
String[]	getDefaultSqlOfAllStatements(boolean leavePrompts)	Returns the statements that will be send to the database. The result depends on the used DataFactories classes.
int	getDocumentPageCount()	Returns the number of pages in the finally document, e.g.
static List<com.inet.font.FontFamily>	getEmbeddableFontNames()	Returns true type font names for all fonts from fontPath (set in the i-net Clear Reports configuration) that are licensed for embedding. Note 1: true type collection file (.ttc) can contain multiple true type fonts Note 2: each true type font can have one or more font names and all these names will be listed Note 3: as a result the number of true type font names returned does not coincide with the number of font files in font directory.
String	getErrorMsg()	Returns the error message as string.
FacturXSettings	getFacturXSettings()	Get the factur X settings.
@Nonnull Fields	getFields()	Returns a new Fields Object.
byte[]	getFontData(int fontID)	Returns the byte array of the embedded font at the specified fontId, encoded in the Viewer's protocol.
String	getGF()	Returns the group selection formula used in the current main or subreport. This could be specified in the report template (rpt file) at design time, with the method setGF or with the report url parameter "gf", see: Report URL Parameters.
FormulaField	getGFField()	Returns the group selection formula used in the current main or subreport as a field. This could be specified in the report template (rpt file) at design time, with the method setGF or with the report url parameter "gf", see: Report URL Parameters.
Group	getGroup(int grNum)	Returns the grouping with the specified number, where number is greater than 1 or lesser than count of groupings.
Group	getGroupByField(Field field)	Returns the group which is based on the parameter field if exists - otherwise null is returned.
int	getGroupCount()	Returns the count of groupings in report without the count of page, report and detail area pairs.
byte[]	getGroupTree()	Returns the group tree which can be sent to the java viewer as a byte array.
Exception[]	getLoadExceptions()	If one or more errors occurred while loading a report template, you can get this error(s) as Exception[] from engine.
Locale	getLocale()	Returns the locale that is used by the renderer.
static int	getLogLevel()	Returns the logging/tracing level that is used by the Engine.
static PrintStream	getLogStream()	Returns the logging/tracing PrintStream that is used by the Engine.
static int	getMajorVersion()	Returns the Engine's major version number.
Properties	getMetaProperties()	Returns any meta properties belonging to this engine.
static int	getMinorVersion()	Returns the Engine's minor version number.
RDC.MsgListener	getMsgListener()	Returns the MsgListener for RDC.
int	getNumeralLanguage()	Returns the language of numerals for numbers, date, time and datetime values.
int	getPageCount()	Returns the number of pages (Java Viewer) or chunks (byte arrays in that the report will be streamed to the client) of the report. This method is waiting until the rendering process has been finished. This is useful if you use i-net Clear Reports with external result sets or connections and you want to know when the rendering process is finished and you can close these external result sets or connections.
byte[]	getPageData(int page)	Returns the data of a single report page.
Engine	getParent()	Returns the parent Engine for the current subreport or null if the current engine is the engine for the main report.
Date	getPrintDate()	Returns the print date for this report.
Object	getPrompt(int i)	Returns the current value for a parameter field in the report.
int	getPromptCount()	Returns the number of prompt fields set for the engine.
PromptField	getPromptField(String name)	Returns the prompt field with the given name (note this is case-insensitive) or null if no such prompt exists.
int	getRecordCount()	Returns count of records this report has read from database.
URL	getReportFile()	Returns the URL of the report template file.
int	getReportID()	Returns the identifier of this report element.
ReportProperties	getReportProperties()	Returns the reports global properties.
String	getReportTitle()	Returns the title of the report specified either in the "Summary Info" dialog of the report designer or with the method setReportTitle. You need to set the report name with the method setReportFile before you can call this method.
List<Section>	getSections()	Returns a list containing all sections the report consists of.
String	getSF()	Returns the record selection formula used in the current main or subreport. This could be specified in the report template (rpt file) at design time, with the method setSF or with the report url parameter "sf", see: Report URL Parameters.
FormulaField	getSFField()	Returns the record selection formula used in the current main or subreport as a formula field. This could be specified in the report template (rpt file) at design time, with the method setSF or with the report url parameter "sf", see: Report URL Parameters.
@Nonnull EngineStatistics	getStatistics()	Runtime statistic data of this Engine.
EngineStatus	getStatus()	Returns an EngineStatus object including information about the status of this Engine .
Engine	getSubReport(int idx)	Every engine object of a main report may have several subreport engines.
int	getSubReportCount()	Returns the number of sub-reports.
Subreport	getSubReportElement()	Returns the subreport element of the main report.
SummaryInfo	getSummaryInfo()	Returns the SummaryInfo class with that you can get/set the report summary info specified in the "Summary Info" of the Reports Designer or with the setXXX methods in the class SummaryInfo. For example: Engine eng = new Engine( Engine.NO_EXPORT ); eng.setReportFile( "file:C:/MyReports/Report1.rpt" ); SummaryInfo su = eng.getSummaryInfo(); System.out.println("created: "+su.getCreated()); System.out.println("LastSaved: "+su.getLastSaved()); System.out.println("Author: "+su.getAuthor()); System.out.println("Subject: "+su.getSubject()); System.out.println("ReportTitle: "+su.getReportTitle());
long	getTime()	Returns the timestamp that was set with setTime.
Translations	getTranslations()	Get the Translations of the report.
Trigger	getTrigger()	Request the Trigger object of this Engine.
Hashtable<Object,Object>	getUserData()	Returns the user data that has been set with setUserData(Hashtable). This method can be useful e.g. in your own database class, a class that extends from com.inet.report.Database and in that you set the report data without a JDBC connection e.g. with an external ResultSet. For instance you can use this method to get the selection formula (sf) specified in the report URL and use it to fill you own ResultSet in your database class:
Properties	getUserProperties()	Returns the user data that has been set either with setUserProperties(), checkProperties() or in the report URL. This method can be useful if you have additional properties which should be associated with the engine.
FormulaField[]	getVariableReferences(String varName)	Returns an array of all FormulaFields referencing the variable with the name varName - this array is empty if there is no such FormulaField referencing the variable.
static String	getVersion()	Returns the release version of this i-net Clear Reports installation, e.g. "8.1.24"
boolean	isDOMParser()	FOR INTERNAL USE ONLY Internal method for reading report XML
boolean	isDrillDownEngine()	FOR INTERNAL USE ONLY Returns this engine is in drill down mode.
boolean	isFinish()	FOR INTERNAL USE ONLY
boolean	isPageLimitExceeded()	Check if the rendering of the report ran into a page limit.
boolean	isSubEngine()	Returns whether this engine is an engine of a subreport (true) or not (false).
void	moveGroup(int source, int dest)	Moves the group with group number source to target.
void	parseDOM(Node node, Map<String,Object> parserMap)	FOR INTERNAL USE ONLY Internal method for reading report XML
NodeParser	parseElement(com.inet.report.parser.XMLTag group, String tag, Attributes atts, Map<String,Object> parserMap)	FOR INTERNAL USE ONLY Internal method for reading report XML
void	parseEndElement(com.inet.report.parser.XMLTag group, String tag, Map<String,Object> parserMap)	FOR INTERNAL USE ONLY Internal method for reading report XML
void	parseText(String text, Map<String,Object> parserMap)	FOR INTERNAL USE ONLY Internal method for reading report XML
void	relocateFile(URL newurl)	FOR INTERNAL USE ONLY Changes the location of the Engine's source.
void	removeClippingListener(ClippingListener listener)	Unregisters a clipping listener with the engine.
void	removeFinishListener(EngineFinishListener listener)	Remove a EngineFinishListener that was added with addFinishListener.
void	removeGroup(int grNum)	Remove the group specified with parameter grNum.
void	removeGroup(Group group)	Removes the given group object from engine.
void	setCatalog(String catalog)	Sets the database name that will be used at runtime instead of the database name that was specified at design time in the report template.
void	setClientLocale(@Nonnull Locale locale)	This method do the same as the method setLocale(Locale) except that the country from the locale of the server is used for the currency format.
void	setConnection(Connection con)	Sets the connection object to the engine of the main- or subreport. You can use this method for instance if you have your own pool of database connections so that you can take the advantage of your own pooled connections. The i-net Clear Reports engine will close the connection after using it, thus indicating to the pool manager that the connection is no longer in use.
void	setConnectionCloseOnFinishing(boolean closeConnectionOnFinishing)	Sets if the set connection should be closed or not be closed after the report executing has been finished.
static void	setCreator(String creator)	Sets the creator string that is visible in the exported files.
void	setData(String[] columns, Object[][] data)	Sets the report data with external data without the use of a JDBC driver.
void	setData(String[] columns, Object[][] data, boolean longColumnNames)	Sets the report data with external data without the use of a JDBC driver.
void	setData(String tableAlias, String[] columns, Object[][] rows)	Set the data for one TableSource.
void	setData(String tableAlias, ResultSet rs)	Set the data for one TableSource.
void	setData(ResultSet resultSet)	Sets the report data with an ResultSet.
void	setData(List<String> columns, List<?> data, boolean longColumnNames)	The columns contains the strings with the columns names.
void	setDataSourceConfigurationName(String datasourceName)	Sets the name of datasource configuration.
void	setDocumentOutput(DocumentOutput pages)	Set the output location for the rendered data.
void	setErrorMsg(String msg)	Sets an error message.
void	setGF(String gf)	Specifies a group selection formula.
void	setLocale(@Nonnull Locale locale)	Sets the locale, which will be used for language independent reports.
static void	setLogLevel(int level)	Sets the logging/tracing level that is used by the Engine.
static void	setLogStream(PrintStream stream)	Sets the logging/tracing PrintStream that is used by the Engine and Viewer.
void	setMetaProperties(Properties props)	Sets (and overwrites!)
void	setMsgListener(RDC.MsgListener msgl)	Sets the MsgListener for RDC.
void	setNumeralLanguage(int language)	Sets the language of the numerals in numbers, date, time and datetime values.
void	setPassword(String password)	Sets the password for the main and all subreports for logging on to SQL, ODBC, or password protected databases used by the report. This function is a convenience function that also sets the password for the main and all sub reports.
void	setPrintDate(Date date)	Sets the print date for this report.
void	setPrompt(String value, int i)	Specifies the value for a parameter field in the report.
void	setPrompt(String name, String value)	Specifies the value for a parameter field in the report. If the name is not in the parameter list the call is ignored. For example: engine.setPrompt("MyDatePrompt","Date(2006,01,03)"); To set the value for a parameter field with multiple values use the array syntax, e.g
void	setPrompts(Vector<?> prompts)	Deprecated. As of i-net Clear Reports 19.0, use setPrompt(PromptField, String), setPrompt(String, int) or setPrompt(String, String)
void	setReportFile(String url)	Sets the report template file.
void	setReportFile(URL url)	Sets the report file URL.
void	setReportTitle(String title)	Sets the title of the report.
void	setSchema(String schema)	Sets the database schema that will be used with this report at runtime instead of the schema that was specified at report creation.
void	setSF(String sf)	Specifies a record selection formula.
void	setSql(String statement)	Replaces all defined tables and joins by this SQL statement.
void	setSql(String statement, boolean useColumnIndexFromReportDesign)	Manually sets the SQL statement that will be send to the database to fetch the report data.
void	setSqlIgnoreMetaData(String statement)	Replaces all defined tables and joins of this report with the supplied sql statement.
void	setTime(long time)	Sets a timestamp.
void	setUser(String user)	Sets the same username for all reports (main and subreports) for logging on to password protected databases used by the report. This function is a convenience function that sets the username for the main and all sub reports.
void	setUserData(Hashtable<Object,Object> hash)	With this method you can associate additional data with the engine and retrieve it later (e.g. in a class that is derived from Database).
void	setUserProperties(Properties props)	With this method you can associate additional data with the engine of the main report.
static void	shutdown()	Attempts to interrupt all Threads created by i-net Clear Reports.
void	stop()	Stops the execution of the report after the rendering of the current page was finished.
void	stop(String message)	Stops the execution of the report after the rendering of the current page was finished.
void	stopAfterPage(int maxPageNo)	Sets the maximum number of report pages rendered by these engine.
static void	stopAll()	Stops all Engines in this JVM or container.

Methods inherited from class java.lang.Object

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

Field Details

AREA_TYPE_REPORT_HEADER

public static final String AREA_TYPE_REPORT_HEADER

Constant for getArea(String): Report Header

See Also:

• Constant Field Values

AREA_TYPE_PAGE_HEADER

public static final String AREA_TYPE_PAGE_HEADER

Constant for getArea(String): Page Header

See Also:

• Constant Field Values

AREA_TYPE_GROUP_HEADER_PREFIX

public static final String AREA_TYPE_GROUP_HEADER_PREFIX

Constant for getArea(String): Group Header Prefix: To access a Group Header, use this prefix in front of the 1-based group index you wish to access. E.g. GH1, GH2...

See Also:

• Constant Field Values

AREA_TYPE_DETAIL

public static final String AREA_TYPE_DETAIL

Constant for getArea(String): Detail Area

See Also:

• Constant Field Values

AREA_TYPE_GROUP_FOOTER_PREFIX

public static final String AREA_TYPE_GROUP_FOOTER_PREFIX

Constant for getArea(String): Group Footer Prefix: To access a Group Footer, use this prefix in front of the 1-based group index you wish to access. E.g. GF1, GF2...

See Also:

• Constant Field Values

AREA_TYPE_REPORT_FOOTER

public static final String AREA_TYPE_REPORT_FOOTER

Constant for getArea(String): Report Footer

See Also:

• Constant Field Values

AREA_TYPE_PAGE_FOOTER

public static final String AREA_TYPE_PAGE_FOOTER

Constant for getArea(String): Page Footer

See Also:

• Constant Field Values

rowCount

protected int rowCount

FOR INTERNAL USE ONLY

REPORT_HEADER

public static final int REPORT_HEADER

The constant for the index number of the report header area.

See Also:

• Constant Field Values

PAGE_HEADER

public static final int PAGE_HEADER

The constant for the index number of the page header area.

See Also:

• Constant Field Values

DETAILS

public static final int DETAILS

The constant for the index number of the details area.

See Also:

• Constant Field Values

REPORT_FOOTER

public static final int REPORT_FOOTER

The constant for the index number of the report footer area.

See Also:

• Constant Field Values

PAGE_FOOTER

public static final int PAGE_FOOTER

The constant for the index number of the report header area.

See Also:

• Constant Field Values

NO_EXPORT

public static final String NO_EXPORT

No export, use java viewer.

Since:

2.01

See Also:

• Constant Field Values

EXPORT_PDF

public static final String EXPORT_PDF

Engine creates PDF output.

Since:

2.01

See Also:

• Constant Field Values

EXPORT_RTF

public static final String EXPORT_RTF

Engine creates RTF output.

Since:

2.01

See Also:

• Constant Field Values

EXPORT_HTML

public static final String EXPORT_HTML

Engine creates HTML output.

Since:

2.01

See Also:

• Constant Field Values

EXPORT_HTML_ZIP

public static final String EXPORT_HTML_ZIP

Engine creates HTML output. All files are packed to a single zip file.

Since:

12.0

See Also:

• Constant Field Values

EXPORT_XLS

public static final String EXPORT_XLS

Engine creates XLS output.

Since:

3.0

See Also:

• Constant Field Values

EXPORT_XLSX

public static final String EXPORT_XLSX

Engine creates XLSX output.

Since:

12.0

See Also:

• Constant Field Values

EXPORT_XML

public static final String EXPORT_XML

Engine creates XML output.

Since:

3.2

See Also:

• Constant Field Values

EXPORT_TXT

public static final String EXPORT_TXT

Engine creates plain text output.

Since:

6.0

See Also:

• Constant Field Values

EXPORT_CSV

public static final String EXPORT_CSV

Engine creates CSV output.
The column delimiter can be specified with property: delimiter.

Since:

7.0

See Also:

• Constant Field Values

EXPORT_PS

public static final String EXPORT_PS

Engine creates postscript output.

Since:

4.2

See Also:

• Constant Field Values

EXPORT_PS2

public static final String EXPORT_PS2

Engine creates postscript 2 output.

Since:

5.1

See Also:

• Constant Field Values

EXPORT_PS3

public static final String EXPORT_PS3

Engine creates postscript 3 output.

Since:

5.1

See Also:

• Constant Field Values

EXPORT_DATA

public static final String EXPORT_DATA

Engine creates data output.

Since:

5.2

See Also:

• Constant Field Values

EXPORT_JSON

public static final String EXPORT_JSON

Engine creates JSON output.

Since:

22.10

See Also:

• Constant Field Values

EXPORT_SVG

public static final String EXPORT_SVG

Engine creates SVG output.

Since:

6.1

See Also:

• Constant Field Values

EXPORT_JRA

public static final String EXPORT_JRA

FOR INTERNAL USE ONLY

See Also:

• Constant Field Values

EXPORT_PNG

public static final String EXPORT_PNG

Engine creates PNG output.

Since:

9.0

See Also:

• Constant Field Values

EXPORT_GIF

public static final String EXPORT_GIF

Engine creates GIF output.

Since:

9.0

See Also:

• Constant Field Values

EXPORT_JPG

public static final String EXPORT_JPG

Engine creates JPG output.

Since:

9.0

See Also:

• Constant Field Values

EXPORT_JPEG

public static final String EXPORT_JPEG

FOR INTERNAL USE ONLY

See Also:

• Constant Field Values

EXPORT_BMP

public static final String EXPORT_BMP

Engine creates BMP output.

Since:

9.0

See Also:

• Constant Field Values

EXPORT_ODS

public static final String EXPORT_ODS

Engine creates OpenOffice ODS output.

Since:

12.0

See Also:

• Constant Field Values

EXPORT_EMAIL

public static final String EXPORT_EMAIL

Engine creates a simplified HTML output which can be used for emails.

Since:

21.10

See Also:

• Constant Field Values

EXPORT_DOCX

public static final String EXPORT_DOCX

Engine creates DOCX output.

Since:

22.10

See Also:

• Constant Field Values

LOG_STATUS

public static final int LOG_STATUS

Log nothing except a status line for each rendered report.

Since:

7.0

See Also:

• Constant Field Values

LOG_ERROR

public static final int LOG_ERROR

Log include error messages such as "report file could not be read, rendering aborted".

Since:

7.0

See Also:

• Constant Field Values

LOG_WARN

public static final int LOG_WARN

Log include warning messages such as "font not found, using a replacement font"

Since:

7.0

See Also:

• Constant Field Values

LOG_INFO

public static final int LOG_INFO

Log include information messages such as the JDBC driver that i-net Clear Reports uses. This log level was default

Since:

7.0

See Also:

• Constant Field Values

LOG_DEBUG

public static final int LOG_DEBUG

Useful if you want to send bug reports to the i-net Clear Reports support at ClearReports@inetsoftware.de

Since:

7.0

See Also:

• Constant Field Values

Constructor Details

Engine

public Engine(String export_fmt)
       throws ReportException

Constructor creates an Engine for different file output formats. Parameters can be set with setUserProperties(Properties).

Parameters:

export_fmt - the output format. The following values are valid:
pdf - PDF file
ps - PS file
ps2 - PS file (level 2)
ps3 - PS file (level 3)
rtf - RTF file
xls - XLS file
xlsx - XLSX file
xml - XML file
csv - CSV file
txt - TXT file
htmBaseFileName - HTML file(s) (e.g. htmMyReport); The base file name is the file name of the first html page (e.g. MyReport.htm) and the base name of all other html files (e.g. MyReport1.htm, MyReport2.htm, ...). Each report page will be saved in a separate HTML file
java - no export; Java Viewer will be used
htm.zip - HTML file(s) packed to a single zip file
data - data file
json - JSON file
svg - SVG file
png - PNG file
gif - GIF file
jpg - JPG file
bmp - BMP file
ods - ODS file
email - email file

For example:

 Engine engine = new Engine(Engine.EXPORT_PDF);
 engine.setReportFile( "file:D:/reports/MySample.rpt" );
 //engine.setPassword("....");    // if you like to change/set the password
 //engine.setPrompt("...","..."); // if you like to set a parameter field value
 engine.execute();
 File pdfFile = new File("D:/exports/sample.pdf");
 FileOutputStream fos = new FileOutputStream(pdfFile);
 for(int i=1;i<=engine.getPageCount();i++){
     fos.write(engine.getPageData(i));
 }
 fos.close();
 

Throws:

ReportException - throw if the format is wrong.

Since:

6.0

See Also:

• RDC.createEmptyEngine(String)
• NO_EXPORT
• EXPORT_PDF
• EXPORT_PS
• EXPORT_PS2
• EXPORT_PS3
• EXPORT_RTF
• EXPORT_HTML
• EXPORT_HTML_ZIP
• EXPORT_XLS
• EXPORT_XLSX
• EXPORT_ODS
• EXPORT_XML
• EXPORT_TXT
• EXPORT_CSV
• EXPORT_DATA
• EXPORT_JSON
• EXPORT_SVG
• EXPORT_BMP
• EXPORT_GIF
• EXPORT_JPG
• EXPORT_PNG
• EXPORT_EMAIL

Method Details

shutdown

public static void shutdown()

Attempts to interrupt all Threads created by i-net Clear Reports. Only use this if you want to dynamically reload an i-net Clear Reports engine (for example for testing different versions of an i-net Clear Reports engine in one VM Session). Warning: Before you re-init an i-net Clear Reports engine the i-net Clear Reports classes must be reloaded by a class loader.

Since:

6.0

getRecordCount

public int getRecordCount()

Returns count of records this report has read from database. For subreports it is the sum of the records of all instances of the subreport. Usable if engine is finished only otherwise returns -1. NOTE: If you need this value for a subreport then you need request the reference of the subreport Engine before execute().

Returns:

count of records or -1

Since:

6.1

setDocumentOutput

public void setDocumentOutput(DocumentOutput pages)

Set the output location for the rendered data. By default the memory (heap) is used. It is also possible to store the data into the report cache or stream it directly to an OutputStream. This must be set before call of execute().

Specified by:

setDocumentOutput in interface ReportGenerator

Parameters:

pages - The location for the data. This can be DocumentOutputStream or CachedOutput.

getCreator

public static String getCreator()

Returns the creator string that i-net Clear Reports writes into the exported files. The default is "i-net Clear Reports <version#>".

Returns:

"i-net Clear Reports " + Engine.getVersion() or whatever has set via setCreator()

Since:

6.0

See Also:

• setCreator(String)

setCreator

public static void setCreator(String creator)

Sets the creator string that is visible in the exported files. For example in the postscript source file the DSC will be "%%Creator: " + Engine.getCreator();

Parameters:

creator - The default value is "i-net Clear Reports " + Engine.getVersion()

Throws:

NullPointerException - If creator is null

Since:

6.0

See Also:

• getCreator()

setLocale

public void setLocale(@Nonnull
 @Nonnull Locale locale)
               throws ReportException

Sets the locale, which will be used for language independent reports. This locale will be used for formating of field values (number, date, time boolean, ... ) and for the translation of labels used in reports into the language specified in the locale. It will be not used for formatting of the result of formula functions like CDbl, ToText etc. The locale is either the one used by the operating system of the client or the one specified in the report URL as property "locale". The strings for the different languages are saved in ResourceBundles. The base class for the ResourceBundles need to be specified in the i-net Clear Reports configuration using the Configuration Manager.
This method also sets the locale for the sub-reports of the engine. If you want to set a different locale for one of the sub-reports then please set the language for the sub-report engine after you've set the language for the main report engine.

Parameters:

locale - The locale to be used by the client

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• getLocale()
• setClientLocale(java.util.Locale)
• setNumeralLanguage(int)

setClientLocale

public void setClientLocale(@Nonnull
 @Nonnull Locale locale)
                     throws ReportException

This method do the same as the method setLocale(Locale) except that the country from the locale of the server is used for the currency format. This method need to be used if the clients in different countries should see the same currency in the reports independent from the locale on the client computer. This method is used from web interface.

Specified by:

setClientLocale in interface ReportGenerator

Parameters:

locale - The locale to be used by the client

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• getLocale()
• setLocale(Locale)

getLocale

public Locale getLocale()
                 throws ReportException

Returns the locale that is used by the renderer.

Returns:

locale The locale used on the client

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• setLocale(Locale locale)

setNumeralLanguage

public void setNumeralLanguage(int language)
                        throws ReportException

Sets the language of the numerals in numbers, date, time and datetime values. This is the global setting of the report. It can be overwritten for each AbstractValueElement.

Parameters:

language - one of the language constant values or -1 for the current locale as default.

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.1

See Also:

• setLocale(Locale)
• getNumeralLanguage()
• ValueProperties.setNumeralLanguage(int)
• ValuePropertiesConstants.NUMERAL_LANGUAGE_EUROPEAN
• ValuePropertiesConstants.NUMERAL_LANGUAGE_ARABIC
• ValuePropertiesConstants.NUMERAL_LANGUAGE_EASTERN_ARABIC
• ValuePropertiesConstants.NUMERAL_LANGUAGE_DEVANAGARI
• ValuePropertiesConstants.NUMERAL_LANGUAGE_BENGALI
• ValuePropertiesConstants.NUMERAL_LANGUAGE_GURMUKHI
• ValuePropertiesConstants.NUMERAL_LANGUAGE_GUJARATI
• ValuePropertiesConstants.NUMERAL_LANGUAGE_ORIYA
• ValuePropertiesConstants.NUMERAL_LANGUAGE_TAMIL
• ValuePropertiesConstants.NUMERAL_LANGUAGE_TELUGU
• ValuePropertiesConstants.NUMERAL_LANGUAGE_KANNADA
• ValuePropertiesConstants.NUMERAL_LANGUAGE_MALAYALAM
• ValuePropertiesConstants.NUMERAL_LANGUAGE_THAI
• ValuePropertiesConstants.NUMERAL_LANGUAGE_LAO
• ValuePropertiesConstants.NUMERAL_LANGUAGE_TIBETAN
• ValuePropertiesConstants.NUMERAL_LANGUAGE_MYANMAR
• ValuePropertiesConstants.NUMERAL_LANGUAGE_ETHIOPIC
• ValuePropertiesConstants.NUMERAL_LANGUAGE_KHMER
• ValuePropertiesConstants.NUMERAL_LANGUAGE_MONGOLIAN

getNumeralLanguage

public int getNumeralLanguage()
                       throws ReportException

Returns the language of numerals for numbers, date, time and datetime values.

Returns:

One of the language constant or -1 for the locale default.

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.1

See Also:

• setNumeralLanguage(int)

setUserProperties

public void setUserProperties(Properties props)
                       throws ReportException

With this method you can associate additional data with the engine of the main report. Later you can use this data e.g. in your own class that is derived from Database.
The data are always attached to the main report engine, never to the sub report engine(s).
To set data for main or subreport engine use the method setUserData(Hashtable). A list and description of interpreted properties can you find in the Report URL Parameters.

Specified by:

setUserProperties in interface ReportGenerator

Parameters:

props - The data to be set in a Properties object.

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• getUserProperties()
• setUserData(Hashtable)
• getUserData()

getUserProperties

public Properties getUserProperties()

Returns the user data that has been set either with setUserProperties(), checkProperties() or in the report URL.
This method can be useful if you have additional properties which should be associated with the engine. But please see also the method set/getUserData(Hashtable data) which is probably more useful.

Returns:

The user properties or null if user properties not set.

Since:

6.0

See Also:

• setUserProperties(Properties props)
• setUserData(Hashtable data)
• getUserData()

getUserData

public Hashtable<Object,Object> getUserData()

Returns the user data that has been set with setUserData(Hashtable).
This method can be useful e.g. in your own database class, a class that extends from com.inet.report.Database and in that you set the report data without a JDBC connection e.g. with an external ResultSet.
For instance you can use this method to get the selection formula (sf) specified in the report URL and use it to fill you own ResultSet in your database class:

   public void getReportData( Engine engine, String configs ) {
       try {
           ...
           // get the url properties from the report URL
           Hashtable p = engine.getUserData();
           String[] cols = p.get("my_cols"));
           ...
           engine.setData(cols, data, true);
       } catch (Throwable t) {Utils.printStackTrace(t);}
    }

In the report URL you can set these parameter, e.g.:
http://<servername>:9000/?report=...rpt&...&sf=table.field=5

Returns:

The user data associated with this report.

Since:

6.0

See Also:

• setUserData(Hashtable)
• setUserProperties(Properties props)
• getUserProperties()

setUserData

public void setUserData(Hashtable<Object,Object> hash)

With this method you can associate additional data with the engine and retrieve it later (e.g. in a class that is derived from Database). The data are always attached to the current engine.

Parameters:

hash - The data to be set.

Since:

6.0

See Also:

• getUserData()
• setUserProperties(Properties props)
• getUserProperties()

getParent

public Engine getParent()
                 throws ReportException

Returns the parent Engine for the current subreport or null if the current engine is the engine for the main report.

Returns:

The parent engine or null.

Throws:

ReportException - if Engine is finished.

Since:

6.0

execute

public void execute()
             throws ReportException

Executes the report and stores the result data in an internal cache. Before you can execute the report generation you need to set all options. You need to call this method before you can request the page data with getPageData.

Specified by:

execute in interface ReportGenerator

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• getPageData(int)

getPageData

public byte[] getPageData(int page)
                   throws ReportException

Returns the data of a single report page. If no export format has been specified for this engine then this method returns the binary data of one report page. These binary data are useful for the Java client only.
If an export format has been specified (e.g. EXPORT_PDF) for this engine [new Engine(Export_Format)] then this method returns the bytes of a report page or of a part (e.g. XLS sheet) of the report. For the export to PDF, RTF, XLS, XML and CSV it is necessary to write the bytes of all pages to a single file to get a valid export file (e.g. .pdf).
If the export to PS is used then it is possible to use the single pages of the .ps file, e.g. for printing.
The html export creates one html file for each report page and one jpg file for each image in the report. Therefore it is necessary to create multiple files from the byte array returned from getPageData (see samples/export/ExportWithoutViewerToHTML.java).

With the following code you can export into a .pdf file:

 Engine engine = new Engine(Engine.EXPORT_PDF);
 engine.setReportFile( "file:D:/reports/MySample.rpt" );
 engine.execute();
 File pdfFile = new File("D:/exports/sample.pdf");
 FileOutputStream fos = new FileOutputStream(pdfFile);
 for(int i=1;i<=engine.getPageCount();i++){
     fos.write(engine.getPageData(i));
 }
 fos.close();
 

Please note: Before you can call this method you need to call engine.execute() to execute and render the report.
This method is waiting until the rendering process of the requested page has been finished.

Specified by:

getPageData in interface ReportGenerator

Parameters:

page - The number of the page. The first page is 1, the second is 2, ... . If the page number is bigger than the page count then null will be returned.

Returns:

the binary data for the Java Viewer or the bytes of the exported file (page).

Throws:

IllegalArgumentException - if the page number is zero or negative.

ReportException - If rendering the page encounters a problem

Since:

6.0

See Also:

• getPageCount()
• Engine(String export_fmt)

getFontData

public byte[] getFontData(int fontID)

Returns the byte array of the embedded font at the specified fontId, encoded in the Viewer's protocol. The fontID is 1-based. null will be returned if there are no fonts embedded for the report of this Engine. If fontID is greater than the number of embedded fonts available it will return the last font available.

Parameters:

fontID - Identifying number of font to fetch

Returns:

the encoded byte array of the embedded font at the specified fontId or null if not font is available.

Throws:

IllegalArgumentException - If fontID is less than 1.

Since:

7.0

isFinish

public boolean isFinish()

FOR INTERNAL USE ONLY

getPageCount

public int getPageCount()
                 throws ReportException

Returns the number of pages (Java Viewer) or chunks (byte arrays in that the report will be streamed to the client) of the report.
This method is waiting until the rendering process has been finished.
This is useful if you use i-net Clear Reports with external result sets or connections and you want to know when the rendering process is finished and you can close these external result sets or connections.

Specified by:

getPageCount in interface ReportGenerator

Returns:

number of pages or chunks

Throws:

ReportException - If rendering the report encounters a problem

Since:

6.0

See Also:

• getPageData(int)
• getDocumentPageCount()

getDocumentPageCount

public int getDocumentPageCount()
                         throws ReportException

Returns the number of pages in the finally document, e.g. PDF file. This is not the same as getPageCount() which returns the number of separate chunks (byte arrays in that the report will be streamed to the client).
This method is waiting until the rendering process has been finished.
This is usefull if you use i-net Clear Reports with external result sets or connections and you want to know when the rendering process is finished and you can close these external result sets or connections.

Returns:

number of pages in the finally document

Throws:

ReportException - If rendering the report encounters a problem

Since:

6.0

See Also:

• getPageCount()

setCatalog

public void setCatalog(String catalog)
                throws ReportException

Sets the database name that will be used at runtime instead of the database name that was specified at design time in the report template. If the used database does not support catalogs (e.g. ORACLE databases) then these parameter will be ignored.
This parameter has an effect only if a catalog was specified at design time. It is not possible to change the catalog if it was not specified at design time.
This function is a convenience function that sets the catalog for the main and all sub reports. Please see the appopriate function in DatabaseTables which only modifies the parameters of the current report.

This method only points to the first datasource of the report and sub reports.

Parameters:

catalog - name of the catalog

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• setDataSourceConfigurationName(String)
• setSchema(String)
• setUser(String)
• setPassword(String)
• DataSourceConfiguration.setCatalog(String)
• DataSourceConfiguration.getCatalog()
• DatabaseTables.createDatasource(String)

setSchema

public void setSchema(String schema)
               throws ReportException

Sets the database schema that will be used with this report at runtime instead of the schema that was specified at report creation. If the used database does not support schema then these parameter will be ignored.
This function is a convenience function that sets the schema for the main and all sub reports. Please see the appopriate function in Datasource which only modifies the parameters of a specific data source.

This method only points to the first datasource of the report and sub reports.

Parameters:

schema - Name of the schema

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• Datasource.getSchema()
• setCatalog(String)
• setDataSourceConfigurationName(String)
• setUser(String)
• setPassword(String)
• Datasource.setSchema(String)
• Datasource.setSchema(String)
• DatabaseTables.createDatasource(String)

setData

public void setData(String[] columns,
 Object[][] data,
 boolean longColumnNames)
             throws ReportException

Sets the report data with external data without the use of a JDBC driver. You only need this function if you do not use a JDBC driver. You can create a rpt template with the report designer or RDC on dummy tables. At runtime you do not have database access.
If a record or group selection formula is set, it will still be evaluated after reading the ResultSet. If you do not wish this, you should remove these formulas with setSF(String) and/or setGF(String).
Note that this does not work with a "query file"; fetching data via a query file takes always precedence even if you call setData().
Example:

Engine eng = new Engine( Engine.NO_EXPORT );
eng.setReportFile( "file:C:/report/MySample.rpt" );
String[] columns = {"TestTable.ID", "TestTable.Name"};
Object[][] data =
{{new Integer(10), "John"},
{new Integer(20), "Peter"},
{new Integer(23), "Ana"}};
eng.setData( columns, data, true );
eng.execute();

Make sure you do not not modify the arrays, columns and data. The Engine does not create a copy of it. The Engine modifies the data array on execute(). Do not use the same array for two calls of setData(). You need to create a copy (for example with clone() ).
As column names it is recommended to set them full qualified: <tableName>. <columnName>

Parameters:

columns - The names of the columns in the report template. This names are case in-sensitiv.

data - the report data. Supported datatypes are: all instances of Number, String and byte[].

longColumnNames - this flag is obsolete since i-net Crystal-Clear 5.3

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• ReportProperties.setIgnoreFiltering(boolean)
• ReportProperties.setIgnoreSorting(boolean)
• setSF(String)
• setGF(String)

setData

public void setData(List<String> columns,
 List<?> data,
 boolean longColumnNames)
             throws ReportException

The columns contains the strings with the columns names. The data can contain object arrays or vectors with the data for the columns. It is a wrapper for the methods with arrays.
If a record or group selection formula is set, it will still be evaluated after reading the ResultSet. If you do not wish this, you should remove these formulas with setSF(String) and/or setGF(String).

Parameters:

columns - must include Strings only

data - can include Vectors or Object[]

longColumnNames - this flag is obsolete since i-net Crystal-Clear 5.3

Throws:

ReportException - If there are problems with the engine not being initialized or with the data not being valid

Since:

6.0

See Also:

• setData(String[],Object[][],boolean)
• ReportProperties.setIgnoreFiltering(boolean)
• ReportProperties.setIgnoreSorting(boolean)
• setSF(String)
• setGF(String)

setData

public void setData(String[] columns,
 Object[][] data)
             throws ReportException

Sets the report data with external data without the use of a JDBC driver. You only need this function if you do not use a JDBC driver. You can create a rpt template with the report designer on dummy tables. At the runtime you do not have database access.
If a record or group selection formula is set, it will still be evaluated after reading the ResultSet. If you do not wish this, you should remove these formulas with setSF(String) and/or setGF(String). Note that this does not work when using a "query file"; fetching data via a query file takes always precedence even if you call setData().
For example:

Engine eng = new Engine( Engine.NO_EXPORT );
eng.setReportFile( "file:C:/report/MySample.rpt" );
String[] columns = {"TestTable.ID", "TestTable.Name"};
Object[][] data =
{{new Integer(10), "John"},
{new Integer(20), "Peter"},
{new Integer(23), "Ana"}};
eng.setData( columns, data );
eng.execute();

Make sure you do not not modify the arrays, columns and data. The Engine does not create a copy of it. The Engine modifies the data array on execute(). Do not use the same array for two calls of setData(). You need to create a copy (for example with clone() ).

Parameters:

columns - The names of the columns in the report template. This names are by default case in-sensitiv.

data - the report data.

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• ReportProperties.setIgnoreFiltering(boolean)
• ReportProperties.setIgnoreSorting(boolean)
• setSF(String)
• setGF(String)

setConnection

public void setConnection(Connection con)
                   throws ReportException

Sets the connection object to the engine of the main- or subreport.
You can use this method for instance if you have your own pool of database connections so that you can take the advantage of your own pooled connections.
The i-net Clear Reports engine will close the connection after using it, thus indicating to the pool manager that the connection is no longer in use. The pool manager can then re-use the real connection.
The main report and each subreport need it's own connection so you need to set separate connections for the main and the subreport(s).

Please note:
1. This method set the catalog to Null. Therefore it is only possible to execute a main or subreport to one database (catalog).
2. The method setConnection() replace the database connection, only. It does not change the settings of the Data Source Configuration on that the report was designed. The driver for a given Data Source Configuration need to be configured as if setConnection() were not used.
3. The properties (like "supports SQL92", "supports brackets in join", "alias keyword", ...) on the Data Source Manager tab "Compatibility Settings" can be used to configure the set connections.

You can find more information about the Data Source Manager in the documentation (click here to read it online).

Code Example:

Class.forName("com.inet.ora.OraDriver");
Engine eng = new Engine( Engine.NO_EXPORT );
eng.setReportFile( "file:C:/report/MySample.rpt" );
Connection con = DriverManager.getConnection("jdbc:inetora:host:port:sid?user=USRName&password=PWD");
eng.setConnection( con );
eng.setCatalog(con.getCatalog());
eng.execute();


Parameters:

con - The database connection object

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• setConnectionCloseOnFinishing(boolean)
• Datasource.setConnection(Connection)

setConnectionCloseOnFinishing

public void setConnectionCloseOnFinishing(boolean closeConnectionOnFinishing)

Sets if the set connection should be closed or not be closed after the report executing has been finished. The default is true.

Parameters:

closeConnectionOnFinishing - if set to false, the set connection will not be closed when the report execution was completed.

Since:

6.0

See Also:

• setConnection(Connection)

stopAfterPage

public void stopAfterPage(int maxPageNo)

Sets the maximum number of report pages rendered by these engine. This method need to be called after setReportFile(...) and before the execution of the engine is finished otherwise it has no effect.

Specified by:

stopAfterPage in interface ReportGenerator

Parameters:

maxPageNo - The last page that should be rendered. 0 means "unlimited".

Since:

6.0

See Also:

• stop()

stop

public void stop()

Stops the execution of the report after the rendering of the current page was finished. This method need to be called after setReportFile(...) and before the execution of the engine is finished otherwise it has no effect.

Since:

6.0

See Also:

• stop(String)
• stopAfterPage(int)
• stopAll()

stop

public void stop(String message)

Stops the execution of the report after the rendering of the current page was finished. This method need to be called after setReportFile(...) and before the execution of the engine is finished otherwise it has no effect.

Specified by:

stop in interface ReportGenerator

Parameters:

message - a message for the debug log.

Since:

7.7

See Also:

• stopAfterPage(int)
• stopAll()

isPageLimitExceeded

public boolean isPageLimitExceeded()

Check if the rendering of the report ran into a page limit. This means does not all possible pages exist.

Returns:

true, if there is a limit

Since:

10.0

stopAll

public static void stopAll()

Stops all Engines in this JVM or container.

Since:

6.0

See Also:

• stop()

setData

public void setData(ResultSet resultSet)
             throws NullPointerException,
SQLException,
ReportException

Sets the report data with an ResultSet. You can create a report file with the report designer on dummy tables (i.e. create a report file that accesses a database). At runtime you can set different ResultSet's for the same report template.
If a record or group selection formula is set, it will still be evaluated after reading the ResultSet. If you do not wish this, you should remove these formulas with setSF(String) and/or setGF(String).
Note: This does not work when using a "query file";
To fetching data via a query file takes always precedence even if you call setData().
Example:

Engine eng = new Engine( Engine.NO_EXPORT );
eng.setReportFile("file:C:/report/MySample.rpt" );
eng.setData( resultSet );
eng.execute();


Parameters:

resultSet - The resultset that contains the data for the report.

Throws:

SQLException - If a database access error occurs or the ResultSet is closed

ReportException - If the Engine is not initialized or finished

NullPointerException - Rarely, if there are internal problems with the database connection. Should never occur.

Since:

6.0

See Also:

• ReportProperties.setIgnoreFiltering(boolean)
• ReportProperties.setIgnoreSorting(boolean)
• setSF(String)
• setGF(String)

setData

public void setData(String tableAlias,
 ResultSet rs)
             throws ReportException

Set the data for one TableSource.

Parameters:

tableAlias - the alias of a TableSource

rs - the data

Throws:

ReportException - if tableAlias was not found in the report

Since:

12.1

setData

public void setData(String tableAlias,
 String[] columns,
 Object[][] rows)
             throws ReportException

Set the data for one TableSource.

Parameters:

tableAlias - the alias of a TableSource

columns - the column names of the data without tablename

rows - the rows of the data

Throws:

ReportException - if tableAlias was not found in the report

Since:

12.1

setLogStream

public static void setLogStream(PrintStream stream)

Sets the logging/tracing PrintStream that is used by the Engine and Viewer.

Parameters:

stream - Print Stream

Since:

6.0

setLogLevel

public static void setLogLevel(int level)

Sets the logging/tracing level that is used by the Engine. This value will be override if i-net Clear Reports is initialize. The initialization is trigger from creating the first Engine, setting a Configuration in the ConfigurationManager and some other API calls.

Parameters:

level - the log level

Since:

6.0

See Also:

• setLogStream(java.io.PrintStream)
• getLogLevel()
• LOG_STATUS
• LOG_ERROR
• LOG_WARN
• LOG_INFO
• LOG_DEBUG

getLogStream

public static PrintStream getLogStream()

Returns the logging/tracing PrintStream that is used by the Engine.

Returns:

Print Stream

Since:

6.0

getLogLevel

public static int getLogLevel()

Returns the logging/tracing level that is used by the Engine.

Returns:

log level

Since:

6.0

See Also:

• setLogLevel(int)

setGF

public void setGF(String gf)
           throws ReportException

Specifies a group selection formula. This parameter is similar to the SF command (selection formula). What you assign here are CrystalReports expressions. For example: engine.setGF("if ({table.row} = 1) then true else false");
The expression is never evaluated on the database server. It is evaluated by the report engine after all records have been fetched and grouped. The formula must return true or false.

Parameters:

gf - group selection formula

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• getGF()
• setSF(java.lang.String)
• getSF()

getGF

public String getGF()
             throws ReportException

Returns the group selection formula used in the current main or subreport.
This could be specified in the report template (rpt file) at design time, with the method setGF or with the report url parameter "gf", see: Report URL Parameters. *

Returns:

group selection formula

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• setGF(java.lang.String)
• setSF(java.lang.String)
• getSF()

getGFField

public FormulaField getGFField()
                        throws ReportException

Returns the group selection formula used in the current main or subreport as a field.
This could be specified in the report template (rpt file) at design time, with the method setGF or with the report url parameter "gf", see: Report URL Parameters. *

Returns:

group selection formula as a field

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• getGF()
• setGF(java.lang.String)
• setSF(java.lang.String)

setSF

public void setSF(String sf)
           throws ReportException

Specifies a record selection formula. Use it to select the records that you want included in your report; of course only if you do not want all records.
If the record selection formula is executable on the database (e.g. a record selection formula that contains an if then construct is not executable on the database) then it will be appended to the 'Where'-clause of the SQL statement.
If it is not executable on the database then i-net Clear Reports will execute it after the data was fetched from the database.
The result of the selection formula need to be a boolean, that means 'true' or 'false'.
If you want to use a database field in the new selection formula that was not added to your report at design time or that was not used in the old selection formula, then you have to add it into your report design.
The record selection formula need to be in Crystal Syntax for formulas.
For example: engine.setSF("if ({table.row} = 1) then true else false");
The expression is evaluated either on the database server when the expression could be translated into a where ... clause or by the report engine when fetching records. The formula must return true or false.

Parameters:

sf - record selection formula to use, null if record selection is to be removed.

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• getSF()
• setGF(java.lang.String)
• getGF()

getSF

public String getSF()
             throws ReportException

Returns the record selection formula used in the current main or subreport.
This could be specified in the report template (rpt file) at design time, with the method setSF or with the report url parameter "sf", see: Report URL Parameters.

Returns:

selection formula or null if no selection formula is set

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• setSF(java.lang.String)
• setGF(java.lang.String)
• getGF()

getSFField

public FormulaField getSFField()
                        throws ReportException

Returns the record selection formula used in the current main or subreport as a formula field.
This could be specified in the report template (rpt file) at design time, with the method setSF or with the report url parameter "sf", see: Report URL Parameters.

Returns:

selection formula as a formula field or null if no record selection formula is set

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• getSF()
• setSF(java.lang.String)

setPrompt

public void setPrompt(String value,
 int i)
               throws ReportException

Specifies the value for a parameter field in the report. Parameter field values are assigned to parameter fields in that order the parameter field exists in the report.

For example: engine.setPrompt("Date(2001,01,01)", 0);
To set the value for a parameter field with multiple values use the array syntax, e.g.:
engine.setPrompt("[Date(2001,01,01),Date(2007,05,15)]", 0);
To set a string value with quotation marks at the beginning and at the end which should be displayed in the report, you need to add additional quotation marks, e.g.:
engine.setPrompt("MyStringPrompt","\"\"string-value\"\"");.

Note: The expression will be executed before any data will be fetched from the database.

Specified by:

setPrompt in interface ReportGenerator

Parameters:

value - value for parameter field i

i - index in the parameter list

Throws:

ReportException - if Engine is not initialized or finished.

IllegalStateException - If no prompt could be found at the given index

Since:

6.0

See Also:

• setPrompts(java.util.Vector<?>)
• getPrompt(int)
• getFields()
• Fields.getPromptField(int)

setPrompt

public void setPrompt(String name,
 String value)
               throws ReportException

Specifies the value for a parameter field in the report.
If the name is not in the parameter list the call is ignored.

For example: engine.setPrompt("MyDatePrompt","Date(2006,01,03)");
To set the value for a parameter field with multiple values use the array syntax, e.g.:
engine.setPrompt("MyDatePrompt","[Date(2001,01,01),Date(2007,05,15)]");.
To set a value with quotation marks at the beginning and at the end which should be displayed in the report, you need to add additional quotation marks, e.g.:
engine.setPrompt("MyStringPrompt","\"\"string-value\"\"");.

Note: The expression will be executed before any data will be fetched from the database.

Note also that if you want to set the value of a prompt in a subreport, you should use the following syntax: #SubreportID#Name
For example: #2#TestName would address a prompt called "TestName" in the second subreport.

Specified by:

setPrompt in interface ReportGenerator

Parameters:

name - the name of the parameter field

value - value for parameter field as String

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• setPrompts(java.util.Vector<?>)
• getPrompt(int)
• getFields()
• Fields.getPromptField(int)

setPrompts

@Deprecated
public void setPrompts(Vector<?> prompts)
                throws ReportException

Deprecated.

As of i-net Clear Reports 19.0, use setPrompt(PromptField, String), setPrompt(String, int) or setPrompt(String, String)

Specifies value for parameter fields in the report. Only String values are accepted in the Vector. If you want set Object values then you need to do this with getFields().getPromptField(x).setPromptValue(value). Parameter field values are assigned to parameter fields in that order the parameter field exists in the report.
Make sure that parameter field values appear in the Vector in the same order the parameter fields appears in the report.

For example:
Vector prompts = new Vector();
prompts.add("Date(2006,01,03)");
...
engine.setPrompt(prompts);

Note: The expression will be executed before any data will be fetched from the database.

Parameters:

prompts - Vector containing parameter field values as String objects, e.g.: "Date(2005,31,12)"

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• getFields()
• Fields.getPromptField(int)

getPrompt

public Object getPrompt(int i)
                 throws ReportException

Returns the current value for a parameter field in the report.

Parameters:

i - index in the parameter list

Returns:

parameter field value

Throws:

ReportException - if Engine is not initialized or finished.

IndexOutOfBoundsException - if there is no parameter field at the index i.

Since:

6.0

See Also:

• setPrompts(java.util.Vector<?>)

getPromptField

public PromptField getPromptField(String name)
                           throws ReportException

Returns the prompt field with the given name (note this is case-insensitive) or null if no such prompt exists.

Specified by:

getPromptField in interface ReportGenerator

Parameters:

name - name of the prompt to fetch

Returns:

PromptField by the given name in this Report, or null if none exists

Throws:

ReportException - if Engine is not initialized or finished.

Since:

14.1

getPromptCount

public int getPromptCount()

Returns the number of prompt fields set for the engine. Prompt fields can be retrieved from the engine using getPrompt(int) or getPromptField(String)

Returns:

number of prompt fields

Since:

19.0

setSql

public void setSql(String statement)
            throws ReportException

Replaces all defined tables and joins by this SQL statement. If a record or group selection formula is set, it will still be evaluated after reading the ResultSet. If you do not wish this, you should remove these formulas with setSF(String) and/or setGF(String). This will cause a query to the database for the meta data of the supplied SQL statement. If not all required columns have been specified in the supplied SQL statement this will throw a ReportException with error code 1212.
Note: This can cause a loss of performance or fail for complex SQL statements. If you experience any problem with this method you should use setSqlIgnoreMetaData(String) instead which will not query the meta data for the SQL statement. Please also note that in this case no ReportException will be thrown if the SQL statement does not contain all required columns for the report. The error will occur at execution then. (error code 14)

Parameters:

statement - The SQL statement

Throws:

ReportException - If not all required columns have been specified in the supplied SQL statement (error code 1212) or an error occurred during setting the SQL statement.

Since:

6.0

See Also:

• TableSource.getSql()
• setSF(String sf)
• setSqlIgnoreMetaData(String)
• ReportProperties.setIgnoreFiltering(boolean)
• ReportProperties.setIgnoreSorting(boolean)

setSqlIgnoreMetaData

public void setSqlIgnoreMetaData(String statement)
                          throws ReportException

Replaces all defined tables and joins of this report with the supplied sql statement. In contrast to setSql(String) this call will not check the supplied sql statement to return all required columns for the report. This means that no request for meta data information will be sent to the database.
If a record or group selection formula is set, it will still be evaluated after reading the ResultSet. If you do not wish this, you should remove these formulas with setSF(String) and/or setGF(String).
Note: As this will not check if all required columns have been specified in the supplied sql statement it is not guaranteed that the report will work with the sql statement. If not all required columns have been specified this will cause a ReportExeption with error code 14 after the engine has been executed with execute(). You can check if an error occurred during rendering by calling getErrorMsg() after execution.

Parameters:

statement - The sql statement which should be executed for this report.

Throws:

ReportException - If an error occurred during setting the sql statement.

Since:

7.5

See Also:

• setSql(String)
• ReportProperties.setIgnoreFiltering(boolean)
• ReportProperties.setIgnoreSorting(boolean)
• setSF(String)
• setGF(String)

setSql

public void setSql(String statement,
 boolean useColumnIndexFromReportDesign)
            throws ReportException

Manually sets the SQL statement that will be send to the database to fetch the report data. If you set a sql statement then this statement will work like a stored procedure that means that the long names "table.column" are not available but only the short name "column".
Instead of using setSql directly, it often can make more sense to call engine.setSF() which overrides the record selection formula ("where ...").
If you want to use long column names (for example table1.field1), then you should set useColumnIndexFromReportDesign to true. This method is meant for advanced users who wish to manually enter their own SQL statment. Note that this is only possible if the report design contains the column names specified in your statement. Furthermore you must create a select statement that matches the column index in the report design (for example you could use the original select statement from the report designer and then modify the where and order by clause only).

Parameters:

statement - The SQL statement

useColumnIndexFromReportDesign - is obsolete.

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• TableSource.getSql()
• setSF(String sf)
• getDefaultSqlOfAllStatements(boolean)

getDefaultSqlOfAllStatements

public String[] getDefaultSqlOfAllStatements(boolean leavePrompts)
                                      throws ReportException

Returns the statements that will be send to the database.
The result depends on the used DataFactories classes. Non JDBC DataFactories produce an empty string. NOTE: If there are prompt fields in the record selection formula and the prompts are not yet set and 'leavePrompts' is set to false, the prompt fields will be replaced by #CONSTANT ...# placeholders to indicate, that some parts of the statement will be constant at runtime but don't have a final value yet.

Parameters:

leavePrompts - If true, PromptFields used in the statement will be replaced by its placeholder.

Returns:

The statements that will be send to the database.

Throws:

ReportException - If creating the statements failed or the engine is finished.

Since:

6.0

See Also:

• setSql(String)

setUser

public void setUser(String user)
             throws ReportException

Sets the same username for all reports (main and subreports) for logging on to password protected databases used by the report.
This function is a convenience function that sets the username for the main and all sub reports. Please see the appopriate function in DataSourcConfiguration which only modifies the username of the current datasource.
Note that this method only points to the first Datasource of the report and sub reports.

Parameters:

user - username for all reports (inclusive subreports)

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• setPassword(String)
• getDatabaseTables()
• DataSourceConfiguration.setUser(String)

setPassword

public void setPassword(String password)
                 throws ReportException

Sets the password for the main and all subreports for logging on to SQL, ODBC, or password protected databases used by the report.
This function is a convenience function that also sets the password for the main and all sub reports. Please see the appopriate function in DataSourceConfiguration which only modifies the parameters of the current datasource.
Note that this method only points to the first Datasource of the report and sub reports.

Parameters:

password - password(s)

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• setUser(String)
• getDatabaseTables()
• DataSourceConfiguration.setPassword(String)

setErrorMsg

public void setErrorMsg(String msg)

Sets an error message. This error message can be requested with getErrorMsg().

Parameters:

msg - the error message.

Since:

6.0

See Also:

• getErrorMsg()

getErrorMsg

public String getErrorMsg()

Returns the error message as string. If there is no error or if the report has not been completely finished, null is returned. To check whether the engine is done, use isFinish().

Returns:

error message, or null if the report was not finished or there was no error.

Since:

6.0

See Also:

• setErrorMsg(java.lang.String)

getFields

@Nonnull
public @Nonnull Fields getFields()
                          throws ReportException

Returns a new Fields Object.

Example: getting names and values of all parameterfields (prompts) and printing them to stdout

// getting all fields, where eng referenzes your Engine - instance, you want to use
Fields fields = eng.getFields();
// getting count of prompts
int promptsCount = fields.getPromptFieldsCount();
PromptField promptField = null;
// for all prompts in fields
for (int i=0;i<promptsCount;i++){
// getting single PromptField at position i
promptField = (PromptField)getPromptField( i );
// print name and value to stdout
System.out.println(promptField.getName() + " : " + promptField.getPrompValue());
}

Note that PromptField.getPromptValue() returns an Object, so check whether you need to cast or not.

Returns:

new Fields Object

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• Fields
• PromptField
• FormulaField
• DatabaseField
• SQLField
• SortField
• GroupField
• SummaryField

getSubReport

public Engine getSubReport(int idx)
                    throws ReportException

Every engine object of a main report may have several subreport engines. This method returns the i'th subreport engine of the current main report. The range is from 0..n.

Parameters:

idx - The 0-based index of subreport

Returns:

the subreport engine

Throws:

ReportException - will thrown if no subreport is available, or idx is greater than size of subreport set or if Engine is not initialized or finished.

Since:

6.0

See Also:

• getSubReportCount()

getSubReportElement

public Subreport getSubReportElement()
                              throws ReportException

Returns the subreport element of the main report. Use this method to get the corresponding element of the current subengine. If the current engine is a main report this methode will return null.

Returns:

subreport element of this engine or null if current engine is a main report engine.

Throws:

ReportException - if Engine is not initialized or engine is finished

Since:

6.0

getSubReportCount

public int getSubReportCount()
                      throws ReportException

Returns the number of sub-reports.

Returns:

the number of sub-reports

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• getSubReport(int idx)

setDataSourceConfigurationName

public void setDataSourceConfigurationName(String datasourceName)
                                    throws ReportException

Sets the name of datasource configuration. All information to create the Connection will be used from this configuration. This function is a convenience function that sets the datasource name for the main report and all sub reports. Please see the appropriate function in DatabaseTables which only modifies the parameters of the current report. You can also set not existing values and save the report before you deploy it in an environment.

This method only points to the first Datasource of the report and sub reports.

Parameters:

datasourceName - Name of the datasource configuration

Throws:

ReportException - if Engine is not initialized or finished.

Since:

9.0

See Also:

• setCatalog(String)
• Datasource.setDataSourceConfigurationName(String)
• getDatabaseTables()
• DatabaseTables.getDatasource(int)

getMajorVersion

public static int getMajorVersion()

Returns the Engine's major version number.

Returns:

Major version of the engine

Since:

6.0

See Also:

• getMinorVersion()
• getVersion()

getMinorVersion

public static int getMinorVersion()

Returns the Engine's minor version number.

Returns:

Minor version of the engine

Since:

6.0

See Also:

• getMajorVersion()
• getVersion()

getVersion

public static String getVersion()

Returns the release version of this i-net Clear Reports installation, e.g. "8.1.24"

Returns:

Version of the engine as a String

Since:

6.0

See Also:

• getMajorVersion()
• getMinorVersion()

getReportFile

public URL getReportFile()
                  throws ReportException

Returns the URL of the report template file.

Returns:

URL of the report template file

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• setReportFile(String)
• setReportFile(java.net.URL)

getSummaryInfo

public SummaryInfo getSummaryInfo()
                           throws ReportException

Returns the SummaryInfo class with that you can get/set the report summary info specified in the "Summary Info" of the Reports Designer or with the setXXX methods in the class SummaryInfo.
For example:

Engine eng = new Engine( Engine.NO_EXPORT );
eng.setReportFile( "file:C:/MyReports/Report1.rpt" );
SummaryInfo su = eng.getSummaryInfo();
System.out.println("created: "+su.getCreated());
System.out.println("LastSaved: "+su.getLastSaved());
System.out.println("Author: "+su.getAuthor());
System.out.println("Subject: "+su.getSubject());
System.out.println("ReportTitle: "+su.getReportTitle());

Returns:

SummaryInfo object of this report with information about when the report was created, last saved, as well as other information

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• SummaryInfo

getTranslations

public Translations getTranslations()
                             throws ReportException

Get the Translations of the report.

Returns:

the Translations associate with the current report, never null

Throws:

ReportException - if Engine is not initialized or finished.

Since:

9.1

getReportTitle

public String getReportTitle()
                      throws ReportException

Returns the title of the report specified either in the "Summary Info" dialog of the report designer or with the method setReportTitle.
You need to set the report name with the method setReportFile before you can call this method.

Returns:

the value of the report title.

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• setReportTitle(String)
• setReportFile(String)

setReportTitle

public void setReportTitle(String title)
                    throws ReportException

Sets the title of the report. This overrides the title in the rpt file summary. You can use this value in the report template with the Special Field "Report Title".
You need to call this method after the call of setReportFile.

Parameters:

title - the value of the new title.

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• getReportTitle()

setTime

public void setTime(long time)

Sets a timestamp. This function can be used to make a timestamp for the last request. This can be used to manage an engine pool in a webserver. This has no effect to the engine.

Parameters:

time - the time in millis.

Since:

6.0

See Also:

• getTime()
• getCacheSize()

getTime

public long getTime()

Returns the timestamp that was set with setTime.

Returns:

time in millis.

Since:

6.0

See Also:

• setTime(long)
• getCacheSize()

getCacheSize

public int getCacheSize()

This function returns the current cache size. This is the size of the binary page data. A servlet or a report server (for example the com.inet.report.Listener) can use it to limit the size of all cached reports for all users.

Returns:

number of bytes of the binary data.

Since:

6.0

setReportFile

public void setReportFile(String url)
                   throws ReportException

Sets the report template file. This is the main method. You need to call this method at first after you have instanciated the engine. If the URL does not include a protocol then it will be encoded. If the URL include a protocol then it must already be encoded, if needed.
For example:

 Engine engine = new Engine( ... );
 engine.setReportFile( ... );
 ...
 

Parameters:

url - the url of the report template file.

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• setReportFile(java.net.URL)
• RDC.loadEngine(File)
• RDC.loadEngine(File, String)
• RDC.loadEngine(URL, java.io.InputStream, String, Properties)

relocateFile

public void relocateFile(URL newurl)
                  throws ReportException

FOR INTERNAL USE ONLY Changes the location of the Engine's source. This is a convenience function used for the designer. It allows you to modify the original location.

Parameters:

newurl - The new URL location for this Engine.

Throws:

ReportException - This Engine has been finished and is not allowed to be used anymore.

Since:

6.0

setReportFile

public void setReportFile(URL url)
                   throws ReportException

Sets the report file URL. This is the main method. You need to call this method at first after you have instanciated the engine.
For example:

 Engine eng = new Engine(...);
 eng.setReportFile( ... );
 ...
 

Parameters:

url - the url of the report template file.

Throws:

ReportException - if Engine is not initialized or finished.

Since:

6.0

See Also:

• setReportFile(String)
• RDC.loadEngine(File)
• RDC.loadEngine(File, String)
• RDC.loadEngine(URL, java.io.InputStream, String, Properties)

getGroupTree

public byte[] getGroupTree()
                    throws ReportException

Returns the group tree which can be sent to the java viewer as a byte array.

Returns:

byte[] Group Tree as byte array.

Throws:

ReportException - If a problem occurs while group tree creation

Since:

6.0

getSections

public List<Section> getSections()
                          throws ReportException

Returns a list containing all sections the report consists of.

Returns:

a read-only list of all sections contained in the report

Throws:

ReportException - if the engine is finished

Since:

6.0

getArea

public Area getArea(int idx)
             throws ReportException

Returns an AreaElement of the Area set. The index specifies the returned Area-Element, where
0 - report header,
1 - page header,
2 - details,
3 - reports footer and
4 - page footer.

if this report is a main report.
Group/Summary area pairs are inserted from position 5. So if your report contains two groups, the areas 5/6 and 7/8 hold the group header/footer for the two groups.
Note: If this report is an embedded subreport the indicies 1 (for page header) and 4 (for page footer) does not exists and null will returned. To get group 1 header use idx=5. To get group 1 footer use idx=6, to get group 2 header use idx=7 etc. (same as main reports).

Parameters:

idx - The 0-based index of returned Area in set.

Returns:

Area object specified by the given index

Throws:

ReportException - if Engine is finished

IndexOutOfBoundsException - If there is no area specified by the given index

Since:

6.0

See Also:

• PAGE_FOOTER
• PAGE_HEADER
• DETAILS
• REPORT_HEADER
• REPORT_FOOTER
• Area

getArea

public Area getArea(String item)
             throws ReportException

Returns an area element of the set of areas. The item specifies the returned area element.

Parameters:

item - Specifies the returned area (using the AREA_TYPE constants)
Note: If this report is an embedded subreport, AREA_TYPE_PAGE_HEADER and AREA_TYPE_PAGE_FOOTER will not work, since these areas do not exist and null will returned.

Returns:

Area object of the area type specified

Throws:

ReportException - if Engine is finished

IllegalArgumentException - If the given area type is not valid. Valid types are defined by the AREA_TYPE constants

Since:

6.0

See Also:

• getArea(int)
• AREA_TYPE_REPORT_HEADER
• AREA_TYPE_PAGE_HEADER
• AREA_TYPE_GROUP_HEADER_PREFIX
• AREA_TYPE_DETAIL
• AREA_TYPE_GROUP_FOOTER_PREFIX
• AREA_TYPE_REPORT_FOOTER
• AREA_TYPE_PAGE_FOOTER

getAreaCount

public int getAreaCount()
                 throws ReportException

Returns the number of Areas of the report. A report can consist of a page area (except sub reports), a report area, a detail area and as many group areas as there are groups in the report.

Returns:

the number of Areas of this report

Throws:

ReportException - if Engine is finished or no report is set.

Since:

6.0

getDatabaseTables

public DatabaseTables getDatabaseTables()
                                 throws ReportException

Returns the DatabaseTables object for this report. You need this object if you want to modify the data source and/or if you want to add or remove tables, stored procedures, joins or if you want to read the data source from a query file.

Returns:

DatabaseTables object for this report, containing information about datasources and table sources referenced and used by this report.

Throws:

ReportException - if Engine is finished or no report is set.

Since:

6.0

See Also:

• DatabaseTables

addGroup

public Group addGroup(Field groupField)
               throws ReportException

Adds a newly created grouping into the grouping set and returns it. The data in this grouping will be sorted by the specified field.

Parameters:

groupField - Field to group the data in the newly created group by.

Returns:

The newly created Group object.

Throws:

ReportException - if the engine is finished, or the report structure is corrupt

Since:

6.0

See Also:

• Group
• addGroup(Field)
• getGroup(int)
• getGroupCount()
• removeGroup(Group)
• removeGroup(int)

getGroupCount

public int getGroupCount()
                  throws ReportException

Returns the count of groupings in report without the count of page, report and detail area pairs.

Returns:

The count of groupings in report.

Throws:

ReportException - if Engine is not initialized or finished.

IllegalStateException - If the Engine has not been initialized correctly

Since:

6.0

See Also:

• Group
• addGroup(Field)
• getGroup(int)
• removeGroup(Group)
• removeGroup(int)

removeGroup

public void removeGroup(Group group)
                 throws ReportException

Removes the given group object from engine.

Parameters:

group - The group which should be removed.

Throws:

ReportException - Thrown if the group is not in engine or the engine is finished

Since:

6.0

removeGroup

public void removeGroup(int grNum)
                 throws ReportException

Remove the group specified with parameter grNum. The value of the paramter must be between 1 and count of groups in the report. Otherwise, and if no group was specified, an exception will be thrown.

Parameters:

grNum - The 1-based number of the group which should be removed. Must be between 1 and count of groups. At least one group should be defined in the report. Use Group.indexOf() when having the group object.

Throws:

ReportException - will be thrown if the value of the parameter is greater than count of groups defined in the report, if no groups were defined in the report or if the value of the parameter is less than 1. If the Engine is finished.

Since:

6.0

See Also:

• Group
• addGroup(Field)
• getGroup(int)
• getGroupCount()
• Group.indexOf()
• removeGroup(Group)

getGroup

public Group getGroup(int grNum)
               throws ReportException,
IndexOutOfBoundsException

Returns the grouping with the specified number, where number is greater than 1 or lesser than count of groupings.

Parameters:

grNum - The 1-based number of the grouping which should be returned. Must be between 1 and count of groupings in report.

Returns:

With parameter grNum specified grouping.

Throws:

ReportException - if Engine is not initialized or finished.

IndexOutOfBoundsException - If the given index does not specify an actual group

Since:

6.0

See Also:

• Group
• addGroup(Field)
• getGroupCount()
• removeGroup(Group)

getGroupByField

public Group getGroupByField(Field field)
                      throws ReportException

Returns the group which is based on the parameter field if exists - otherwise null is returned.

Parameters:

field - The field the Group is based on.

Returns:

Group

Throws:

ReportException - if the engine is finished

Since:

6.0

moveGroup

public void moveGroup(int source,
 int dest)
               throws ReportException

Moves the group with group number source to target.

Parameters:

source - the 1-based number of the group which should moved to target.

dest - the 1-based destination of moving.

Throws:

ReportException - if the engine is finished

Since:

6.0

setPrintDate

public void setPrintDate(Date date)
                  throws ReportException

Sets the print date for this report.

Parameters:

date - Date object to use as the current point in time

Throws:

ReportException - if Engine is finished

Since:

6.0

getPrintDate

public Date getPrintDate()
                  throws ReportException

Returns the print date for this report.

Returns:

The printing time of this report. Might have been changed with setPrintDate(java.util.Date)

Throws:

ReportException - if Engine is finished

Since:

6.0

getLoadExceptions

public Exception[] getLoadExceptions()

If one or more errors occurred while loading a report template, you can get this error(s) as Exception[] from engine. If no errors has occurred null will be returned.

Returns:

Exception[] if an exception has occurred or null

Since:

6.0

setMsgListener

public void setMsgListener(RDC.MsgListener msgl)

Sets the MsgListener for RDC.

Parameters:

msgl - The object which implements the RDC.MsgListener interface and should handle the queries from RDC to the user.

Since:

6.0

getMsgListener

public RDC.MsgListener getMsgListener()

Returns the MsgListener for RDC.

Returns:

The object which implements the RDC.MsgListener interface and should handle the queries from RDC to the user.

Since:

6.0

isSubEngine

public boolean isSubEngine()
                    throws ReportException

Returns whether this engine is an engine of a subreport (true) or not (false).

Returns:

boolean

Throws:

ReportException - if the engine has already been executed.

Since:

6.0

getStatus

public EngineStatus getStatus()

Returns an EngineStatus object including information about the status of this Engine . If this is a sub report Engine this will throw an ReportException.

Returns:

The !EngineStatus object for this Engine .

Throws:

IllegalStateException - If this Engine is a sub report Engine

Since:

8.2

See Also:

• getParent()
• getTrigger()
• getStatistics()

getReportProperties

public ReportProperties getReportProperties()
                                     throws ReportException

Returns the reports global properties.

Returns:

Returns the report properties.

Throws:

ReportException - if Engine is not initialized or finished

Since:

6.0

getFacturXSettings

public FacturXSettings getFacturXSettings()
                                   throws ReportException

Get the factur X settings.

Returns:

Returns the settings.

Throws:

ReportException - if Engine is not initialized or finished

Since:

20.10

getEmbeddableFontNames

public static List<com.inet.font.FontFamily> getEmbeddableFontNames()

Returns true type font names for all fonts from fontPath (set in the i-net Clear Reports configuration) that are licensed for embedding.

Note 1: true type collection file (.ttc) can contain multiple true type fonts
Note 2: each true type font can have one or more font names and all these names will be listed
Note 3: as a result the number of true type font names returned does not coincide with the number of font files in font directory.

Returns:

the list with font names as strings or empty list, if fontPath is not defined or if the font directory contains no true type fonts

Since:

6.0

addClippingListener

public void addClippingListener(ClippingListener listener)

Registers a clipping listener with the engine - any time an element is clipped while rendering, this listener's method "clippingOnElement" is called

Parameters:

listener - Listener to be registered.

Since:

6.1

See Also:

• ClippingListener
• ClippingEvent

removeClippingListener

public void removeClippingListener(ClippingListener listener)

Unregisters a clipping listener with the engine.

Parameters:

listener - Listener to be unregistered.

Since:

6.1

See Also:

• ClippingListener
• ClippingEvent

addFinishListener

public void addFinishListener(EngineFinishListener listener)

Add a EngineFinishListener to this engine. The Listener will be informed if the engine is finish.

Parameters:

listener - EngineFinishListener to notify when the engine is finished rendering.

Since:

6.1

See Also:

• removeFinishListener(com.inet.report.event.EngineFinishListener)
• EngineFinishListener

removeFinishListener

public void removeFinishListener(EngineFinishListener listener)

Remove a EngineFinishListener that was added with addFinishListener.

Parameters:

listener - EngineFinishListener to no longer notify when the engine is done rendering

Since:

6.1

See Also:

• addFinishListener(com.inet.report.event.EngineFinishListener)
• EngineFinishListener

getVariableReferences

public FormulaField[] getVariableReferences(String varName)
                                     throws ReportException

Returns an array of all FormulaFields referencing the variable with the name varName - this array is empty if there is no such FormulaField referencing the variable. Note that only global and shared variables are searched for references, since local variables are only referenced from within a single formula.

Parameters:

varName - The name of the variable to search for references. Case-insensitive.

Returns:

An array of all formula fields referencing this variable.

Throws:

ReportException - if Engine is finished

Since:

6.0

parseElement

public NodeParser parseElement(com.inet.report.parser.XMLTag group,
 String tag,
 Attributes atts,
 Map<String,Object> parserMap)
                        throws FatalParserException

FOR INTERNAL USE ONLY Internal method for reading report XML

Parses an XML node with the given information, and returns either a sub-element which was created as a result, or null if no sub-element was created, i.e. the information was applied to the ReportComponent itself. Note that the parsing is highly tolerant, i.e. exceptions are intercepted and suppressed if at all possible.

Specified by:

parseElement in interface NodeParser

Parameters:

group - XMLTag of the current node to be parsed, or null if there is no such current group. An XMLTag is a group of nodes bundled together, usually it is a Properties node such as CommonProperties, BorderProperties, etc.

tag - The XMLTag to be parsed

atts - The set of attributes in the current XMLTag

parserMap - The map of current Parser.

Returns:

The NodeParser sub-element if one needed to be created, or null if none was created.

Throws:

FatalParserException - if an exception occurs which causes the report to not be able to be read: causes the abortion of the reading of the report.

parseText

public void parseText(String text,
 Map<String,Object> parserMap)

FOR INTERNAL USE ONLY Internal method for reading report XML

This method is called if text was encountered in the context of this node. (Examples would be a formula's text or a text element's text)

Specified by:

parseText in interface NodeParser

Parameters:

text - text encountered and to be stored

parserMap - The map of current Parser.

parseEndElement

public void parseEndElement(com.inet.report.parser.XMLTag group,
 String tag,
 Map<String,Object> parserMap)
                     throws FatalParserException

FOR INTERNAL USE ONLY Internal method for reading report XML

Receive notification of the end of an XML tag.

Specified by:

parseEndElement in interface NodeParser

Parameters:

group - XMLTag of the current node to be parsed, or null if there is no such current group.

tag - The XMLTag to be parsed

parserMap - The map of current Parser.

Throws:

FatalParserException - if an exception occurs which causes the report to not be able to be read: causes the abortion of the reading of the report.

isDOMParser

public boolean isDOMParser()

FOR INTERNAL USE ONLY Internal method for reading report XML

Returns whether this node is to be read via a DOM parser.

Specified by:

isDOMParser in interface NodeParser

Returns:

true if this node is to be read via a DOM parser, false otherwise.

parseDOM

public void parseDOM(Node node,
 Map<String,Object> parserMap)
              throws FatalParserException

FOR INTERNAL USE ONLY Internal method for reading report XML

Parses the node.

Specified by:

parseDOM in interface NodeParser

Parameters:

node - the node

parserMap - The map of current Parser.

Throws:

FatalParserException - if an exception occurs which causes the report to not be able to be read: causes the abortion of the reading of the report.

isDrillDownEngine

public boolean isDrillDownEngine()

FOR INTERNAL USE ONLY Returns this engine is in drill down mode.

Returns:

the flag

getMetaProperties

public Properties getMetaProperties()

Returns any meta properties belonging to this engine. This is NOT a copy but the actual Properties itself - adding or removing properties to this Properties object will add or remove them for this engine. Note that these properties will have NO effect on the rendering of a report. Note also that properties with the prefix "designer" are reserved for use by i-net Designer and should therefore not be used or manipulated. Properties should be string pairs of keys and values: non-string values will lead to issues when saving. See the documentation for Properties

Returns:

purely design-time meta properties of this engine. never null.

Since:

10.0

setMetaProperties

public void setMetaProperties(Properties props)

Sets (and overwrites!) the meta properties which will be stored in the report file if the engine is saved and retrieved if this report file is loaded. Note that these properties will have NO effect on the rendering of a report. Note also that properties with the prefix "designer" are reserved for use by i-net Designer and should therefore not be used or manipulated. Finally, note that any existing meta properties will be overwritten by this method. If you only want to add properties to the report, use getMetaProperties() instead and add your properties to the Properties object.

Parameters:

props - Properties to set. May not be null.

Throws:

IllegalArgumentException - if props is null

Since:

10.0

getReportID

public int getReportID()

Returns the identifier of this report element. In case 0 is returned, this is the main report. If the value is greater zero, it is a subreport.
Please note that this ID is save/load persistant while the subreport index is not. DO NOT use this ID with the function getSubReport(int) since ID and index are different.

Returns:

the ID of this report element

Since:

10.0

getTrigger

public Trigger getTrigger()

Request the Trigger object of this Engine. You need to set the Trigger Formula before you execute the report.

Returns:

the Trigger

Since:

11.1

See Also:

• getStatistics()
• getStatus()

getStatistics

@Nonnull
public @Nonnull EngineStatistics getStatistics()

Runtime statistic data of this Engine.

Specified by:

getStatistics in interface ReportGenerator

Returns:

the statistic

Since:

13.0

See Also:

• getTrigger()
• getStatus()