Job Class Reference

This is the main class of TFORMer SDK for generating output. More...

List of all members.

Public Member Functions
	Job () throws TFormerException
	Job class constructor.
void	dispose () throws TFormerException
	Releases the resources allocated by this instance.
void	print () throws TFormerException
	Prints the Job using the selected FormLayout and the current JobData.
void	printToStream (OutputStream stream) throws TFormerException
	Print the current Job using the selected FormLayout and current JobData.
void	printToStreams (OutputStreamFactory factory) throws TFormerException
	Print the current Job using the selected FormLayout and current JobData.
void	saveXml (String filename) throws TFormerException
	Saves the JobData used for printing a Job as XML file.
Package Functions
String	getPrintResult (DataFormat dataFormat) throws TFormerException
	Gets the data of the last print operation in specified format.
Properties
String	getOptions ()
	Return the additional options for printing and output creation.
void	setOptions (String options)
	Sets additional options for printing and output creation.
String	getConfigurationFile ()
	Gets the current configuration file for TFORMer SDK.
void	setConfigurationFile (String sConfigurationFile)
	Sets the current configuration file for TFORMer SDK.
String	getRepositoryName ()
	Gets the filename of the Repository or the filename of the stand-alone FormLayout for this Job.
void	setRepositoryName (String sRepositoryName)
	Sets the filename of the Repository or the filename of the stand-alone FormLayout for this Job.
String	getProjectName ()
	Gets the name of the Project for printing a Repository-based FormLayout.
void	setProjectName (String sProjectName)
	Sets the name of the Project for printing a Repository-based FormLayout.
String	getFormName ()
	Gets the name of the Repository-based FormLayout for this Job.
void	setFormName (String sFormName)
	Sets the name of the Repository-based FormLayout for this Job.
String	getPrinterName ()
	Gets the type and the name of the output device.
void	setPrinterName (String sPrinterName)
	Sets the name of the output device (file or printer) and the type of the printer (e.g. normal printer, PDF, JPG,....).
int	getNumberOfCopies ()
	Gets the number of copies to be printed.
void	setNumberOfCopies (int numberOfCopies) throws IllegalArgumentException
	Sets the number of copies to be printed.
String	getJobTrayControlName ()
	Gets the name of the JobTrayControl to be used for this Job.
void	setJobTrayControlName (String sJobTrayControlName)
	Sets the name of the JobTrayControl to be used for this Job.
String	getOutputName ()
	Gets the name of the output file or the name of the spool-job (on Microsoft Windows printers).
void	setOutputName (String sOutputName)
	Sets the name of the output file or the name of the spool-job (on Microsoft Windows printers).
int	getFromPage ()
	Gets the first page-number to be printed.
void	setFromPage (int nFromPage)
	Sets the first page-number to be printed.
int	getToPage ()
	Gets the last page-number to be printed.
void	setToPage (int nToPage)
	Sets the last page number to be printed.
int	getStartColumn ()
void	setStartColumn (int startColumn) throws IllegalArgumentException
	Sets the column-number of the first label to be printed.
int	getStartRow ()
	Gets the row-number of the first label to be printed.
void	setStartRow (int startRow) throws IllegalArgumentException
	Sets the row-number of the first label to be printed.
EPrinterType	getPrinterType ()
	Gets the type of the generated output.
void	setPrinterType (EPrinterType printerType)
	Sets the type of the generated output.
JobData	getJobData ()
	Gets the JobData for the Job.
void	setJobData (JobData jobData)
	Sets the JobData for the Job.
PrintResultType	getPrintResultType ()
	Gets the type of data that should be gathered, while printing.
void	setPrintResultType (PrintResultType printResultType)
	Sets the type of data that should be gathered, while printing.

---

Detailed Description

This is the main class of TFORMer SDK for generating output.

Overview

Printing (or more general: producing output) is done with the help of a so-called Job. A Job prints a stand-alone or Repository based FormLayout with dynamic data provided by JobData.

A Job provides various methods for controlling the output behavior. Among other functions it is possible

• to select the target device and the required output format (Output Format Prefixes),
• set Job options (Print Options),
• and to select a specific configuration file (TFORMer.XML Configuration File).

Workflow

The basic steps to generate output are as follows:

1. Select a FormLayout
2. Create JobData
   JobData is used to pass dynamic data to a Job.
3. Provide data for JobData
   The JobData is use to provide values for the DataFields required for the FormLayout to be printed.
   Provide data programmatically or instruct JobData to use a DataSource already defined in the FormLayout (e.g. importing data from a CSV file or a ODBC database). See JobDataRecordSet, JobDataCsv, JobDataOdbc, JobDataXml, JobDataDataSource
4. Create a Job
   The Job class is the main class for printing a FormLayout.
5. Assign the JobData to the Job
   If no JobData is assigned to a Job, the default data for the FormLayout is used. This default data is identical to the data-set which was used for printing or previewing the FormLayout in the last TFORMer Designer session.
6. Adjust the properties of the Job
   The most important properties are the output-type and the name of the target device (setOutputName, setPrinterType or setPrinterName). The order in which the properties are set is irrelevant.
7. Print the Job
   To generate the Job based on the FormLayout and JobData in the required output format use one of the print-methods (print, printToStream, printToStreams) provided by a Job.

More Information

• JobData
  Base class for JobData

Note:

Thread-safety: A single instance of this class must not be used by different threads.

---

Constructor & Destructor Documentation

Job

(

)

throws TFormerException

Job class constructor.

Initializes a new instance of the Job class.

---

Member Function Documentation

void dispose

(

)

throws TFormerException

Releases the resources allocated by this instance.

In order to release allocated memory call this method always after the use of the instance.

String getConfigurationFile

(

)

Gets the current configuration file for TFORMer SDK.

Returns:

The configuration file for TFORMer SDK.

See also:

TFORMer.XML Configuration File

String getFormName

(

)

Gets the name of the Repository-based FormLayout for this Job.

See also:

Repository / FormLayout, FormLayout

Returns:

The name of the Repository-based FormLayout for this Job.

int getFromPage

(

)

Gets the first page-number to be printed.

Returns:

The first page-number to be printed.

JobData getJobData

(

)

Gets the JobData for the Job.

Returns:

The JobData for the Job

See also:

JobData, JobDataCsv, JobDataXml, JobDataOdbc, JobDataDataSource, JobDataRecordSet

String getJobTrayControlName

(

)

Gets the name of the JobTrayControl to be used for this Job.

Returns:

The name of the JobTrayControl to be used for this Job

See also:

JobTrayControl

int getNumberOfCopies

(

)

Gets the number of copies to be printed.

Returns:

The number of copies to be printed

String getOptions

(

)

Return the additional options for printing and output creation.

Returns:

A string containing name/value pairs with the currently adjusted print options.

See also:

Print Options

String getOutputName

(

)

Gets the name of the output file or the name of the spool-job (on Microsoft Windows printers).

Returns:

The name of the output file or the name of the spool-job (on Microsoft Windows printers).

See also:

Output Format Prefixes, setOutputName, setPrinterType, setPrinterName

String getPrinterName

(

)

Gets the type and the name of the output device.

Returns:

The type and name of the output device.

See also:

Output Format Prefixes, setOutputName, setPrinterType, setPrinterName

EPrinterType getPrinterType

(

)

Gets the type of the generated output.

Returns:

The type of the generated output.

See also:

Output Format Prefixes, setOutputName, setPrinterType, setPrinterName

String getPrintResult

(

DataFormat

dataFormat

)

throws TFormerException [package]

Gets the data of the last print operation in specified format.

Call this function after print or printToStreams to get the data that has been gathered while printing. Specify the data to be gathered by a call to before print or printToStreams.

Returns:

The data that has been gathered while printing.

Parameters:

dataFormat

Specifies the format of the data to be returned.

See also:

setPrintResultType, getPrintResultType

PrintResultType getPrintResultType

(

)

Gets the type of data that should be gathered, while printing.

Returns:

The type of data that should be gathered, while printing.

See also:

getPrintResult, setPrintResultType

String getProjectName

(

)

Gets the name of the Project for printing a Repository-based FormLayout.

See also:

Repository / FormLayout

Returns:

The name of the Project for printing a Repository-based FormLayout

String getRepositoryName

(

)

Gets the filename of the Repository or the filename of the stand-alone FormLayout for this Job.

Returns:

The filename of the Repository or the filename of the stand-alone FormLayout for this Job.

See also:

Repository / FormLayout, FormLayout

int getStartColumn

(

)

Gets the column-number of the first label to be printed.

Returns:

The column-number of the first label to be printed (starting from 0).

int getStartRow

(

)

Gets the row-number of the first label to be printed.

Returns:

The row-number of the first label to be printed (starting from 0).

int getToPage

(

)

Gets the last page-number to be printed.

Returns:

The last page-number to be printed.

void print

(

)

throws TFormerException

Prints the Job using the selected FormLayout and the current JobData.

See also:

Basic Concept / Printing, JobData

void printToStream

(

OutputStream

stream

)

throws TFormerException

Print the current Job using the selected FormLayout and current JobData.

The output is available in the provided output stream. Use printToStreams for bitmaps with multiple pages.

Parameters:

stream

Instance of the output stream

See also:

Basic Concept / Printing, JobData

void printToStreams

(

OutputStreamFactory

factory

)

throws TFormerException

Print the current Job using the selected FormLayout and current JobData.

The output is available via multiple output streams created and closed by the provided OutputStreamFactory. With bitmap printer type (e.g. ImagePng) each page is printed on a separate stream.

Parameters:

factory

Instance used to create and close streams when needed

See also:

Basic Concept / Printing, JobData

void saveXml

(

String

filename

)

throws TFormerException

Saves the JobData used for printing a Job as XML file.

This function writes the JobData-cache to the specified file using the internal TFORMer format. This file can later be used for JobDataXml.

Parameters:

filename

The name of the output file.

See also:

JobData

void setConfigurationFile

(

String

sConfigurationFile

)

Sets the current configuration file for TFORMer SDK.

Parameters:

sConfigurationFile

Path and filename of a TFORMer configuration file

See also:

TFORMer.XML Configuration File, Passing Files

void setFormName

(

String

sFormName

)

Sets the name of the Repository-based FormLayout for this Job.

Specifies the name of the FormLayout which is referenced from within a Project of the current Repository.

Parameters:

sFormName

The name of the Repository-based FormLayout for this Job

Note:

Do not use this property for a stand-alone FormLayout.

See also:

Repository / FormLayout, FormLayout

Note:

All cached JobData is discarded.

void setFromPage

(

int

nFromPage

)

Sets the first page-number to be printed.

Parameters:

nFromPage

The first page-number to be printed

Specifies the page number of the first page to be printed. To restore this setting (printing of all pages of the job), execute the following:

  job.setFromPage ( 0 );
  job.setToPage   ( 0 );

void setJobData

(

JobData

jobData

)

Sets the JobData for the Job.

JobData is used to provide DataField values for printing the FormLayout. Different methods for providing JobData are available (see JobData, JobDataCsv, JobDataXml, JobDataOdbc, JobDataDataSource, JobDataRecordSet).

Parameters:

jobData

The JobData for the Job

See also:

JobData, JobDataCsv, JobDataXml, JobDataOdbc, JobDataDataSource, JobDataRecordSet

void setJobTrayControlName

(

String

sJobTrayControlName

)

Sets the name of the JobTrayControl to be used for this Job.

Specify the JobTrayControl for the current Job. If this property is not set then the Job is generated with the JobTrayControl named _Default_.

Parameters:

sJobTrayControlName

The name of the JobTrayControl to be used for this Job

See also:

JobTrayControl

void setNumberOfCopies

(

int

numberOfCopies

)

throws IllegalArgumentException

Sets the number of copies to be printed.

Specifies the number of identical copies produced with one call to print. The default value is 1.

Parameters:

numberOfCopies

The number of copies to be printed

Exceptions:

IllegalArgumentException

An error is raised in case of a negative value.

void setOptions

(

String

options

)

Sets additional options for printing and output creation.

Parameters:

options

The options are passed as name/value pairs delimited by white-spaces in the form of [OptionName]=[value]. [OptionName] without an additional value is treated as if [OptionName]=true is provided. no[OptionName] is treated as if [OptionName]=false is provided

See also:

Print Options

void setOutputName

(

String

sOutputName

)

Sets the name of the output file or the name of the spool-job (on Microsoft Windows printers).

Use setOutputName in conjunction with setPrinterType to specify the type and the target of the generated output. setPrinterName overrides the settings of setOutputName and setPrinterType. Refer to Output Format Prefixes for a description of the supported output formats.

Parameters:

sOutputName

The name of the output file or the name of the spool-job (on Microsoft Windows printers)

See also:

Output Format Prefixes, setOutputName, setPrinterType, setPrinterName

void setPrinterName

(

String

sPrinterName

)

Sets the name of the output device (file or printer) and the type of the printer (e.g. normal printer, PDF, JPG,....).

The function specifies the output format as well as the target device or target filename. Refer to Output Format Prefixes for a description of the supported output formats.

Parameters:

sPrinterName

The type and name of the output device

Note:

This function must be called prior generating output (see print, printToStream or printToStreams).

See also:

Output Format Prefixes, setOutputName, setPrinterType, setPrinterName

void setPrinterType

(

EPrinterType

printerType

)

Sets the type of the generated output.

Use setOutputName in conjunction with setPrinterType to specify the type and the target of the generated output. setPrinterName overrides the settings of setOutputName and setPrinterType. Refer to Output Format Prefixes for a description of the supported output formats.

Parameters:

printerType

The type of the generated output

See also:

Output Format Prefixes, setOutputName, setPrinterType, setPrinterName

void setPrintResultType

(

PrintResultType

printResultType

)

Sets the type of data that should be gathered, while printing.

Call this function before print or printToStreams to specify the data that should be gathered while printing. After the output has been generated the data can be retrieved by a call to getPrintResult.

Parameters:

printResultType

The type of data that should be gathered, while printing.

See also:

getPrintResult, getPrintResultType

void setProjectName

(

String

sProjectName

)

Sets the name of the Project for printing a Repository-based FormLayout.

When using a Repository-based FormLayout use this function to provide the name of the Project. In addition, the name of the FormLayout must be set with Job.setFormName.

Parameters:

sProjectName

The name of the Project for printing a Repository-based FormLayout

Attention:

Do not use this property for a stand-alone FormLayout.

See also:

Repository / FormLayout

Note:

All cached data as well as the actual FormLayout are discarded.

void setRepositoryName

(

String

sRepositoryName

)

Sets the filename of the Repository or the filename of the stand-alone FormLayout for this Job.

Parameters:

sRepositoryName

The filename of the Repository or the filename of the stand-alone FormLayout for this Job

Use this method to provide either the filename of the Repository (*.tfr file) or the stand-alone FormLayout (*.tff file). If you are using a Repository you need to specify the Project (Job.setProjectName) and the FormLayout (Job.setFormName) as well.

See also:

Repository / FormLayout, FormLayout, Passing Files

Note:

When changing the Repository, the Project or the FormLayout all internal cached data is discarded.

void setStartColumn

(

int

startColumn

)

throws IllegalArgumentException

Sets the column-number of the first label to be printed.

Usually TFORMer prints the first label of a label-style report at the first available position of a page (this is the top / left label). This property sets the column number of the first label, the default starting column is 0. To restore the default behavior do the following:

  job.setStartRow    ( 0 );
  job.setStartColumn ( 0 );

Parameters:

startColumn

The column-number of the first label to be printed (leftmost column has index 0)

Exceptions:

IllegalArgumentException

An error is raised in case of a negative value

See also:

setStartRow

void setStartRow

(

int

startRow

)

throws IllegalArgumentException

Sets the row-number of the first label to be printed.

Usually TFORMer prints the first label of a label-style report at the first available position of a page (this is the top / left label). This property sets the row number of the first label, the default starting row is 0.

Parameters:

startRow

The row-number of the first label to be printed (topmost row has index 0)

Exceptions:

IllegalArgumentException

An error is raised in case of a negative value.

See also:

setStartColumn

void setToPage

(

int

nToPage

)

Sets the last page number to be printed.

Specifies the page number of the last page to be printed.

Parameters:

nToPage

The last page number to be printed

See also:

setFromPage