Abstract class for a DataSource. More...

Public Member Functions
ComputedField	addComputedField (String name) throws TFormerException
	Creates and adds a ComputedField to the DataSource. More...

DSFieldMapping	addFieldMapping (String name) throws TFormerException
	Creates and adds a DSFieldMapping to the DataSource. More...

DataSourceParameter	addParameter (String name) throws TFormerException
	Creates and adds a DataSourceParameter to the DataSource. More...

void	dispose () throws TFormerException
	Releases the resources allocated by the instance. More...

void	dump (PrintStream s) throws IOException, TFormerException
	Dumps the current instance into a text stream. More...

String	getComment () throws TFormerException
	Gets the comment for the DataSource. More...

ComputedField	getComputedField (String name) throws TFormerException
	Gets a ComputedField defined in the DataSource. More...

String	getCopyColumnName () throws TFormerException
	Gets the CopyColumnName of the DataSource. More...

String	getDescription () throws TFormerException
	Gets the description of the DataSource. More...

DSFieldMapping	getFieldMapping (String name) throws TFormerException
	Gets a DSFieldMapping defined in the DataSource. More...

ComputedField	getFirstComputedField () throws TFormerException
	Gets the first ComputedField defined in the DataSource. More...

DSFieldMapping	getFirstDSFieldMapping () throws TFormerException
	Gets the first DSFieldMapping defined in the DataSource. More...

DataSourceParameter	getFirstParameter () throws TFormerException
	Gets the first DataSourceParameter defined in the DataSource. More...

String	getName () throws TFormerException
	Gets the name of the DataSource. More...

DataSource	getNext () throws TFormerException
	Gets the next DataSource instance defined in the Project. More...

int	getNumberOfComputedFields () throws TFormerException
	Gets the number of ComputedFields defined in the DataSource. More...

int	getNumberOfFieldMappings () throws TFormerException
	Gets the number of DSFieldMappings defined in the DataSource. More...

int	getNumberOfParameters () throws TFormerException
	Gets the number of DataSourceParameters defined in the DataSource. More...

DataSourceParameter	getParameter (String name) throws TFormerException
	Gets a DataSourceParameter defined in the DataSource. More...

DataSourceType	getType () throws TFormerException
	Gets the type of the DataSource. More...

boolean	isDefault () throws TFormerException
	Gets a value indicating whether this object stores the default DataSource. More...

boolean	isHandleEscapeSequences () throws TFormerException
	Gets if escape sequences should be translated on data retrieval or not. More...

void	removeComputedField (ComputedField computedField) throws TFormerException
	Removes the ComputedField from the DataSource. More...

void	removeComputedField (String name) throws TFormerException
	Removes the ComputedField from the DataSource. More...

void	removeFieldMapping (DSFieldMapping fieldMapping) throws TFormerException
	Removes the DSFieldMapping from the DataSource. More...

void	removeFieldMapping (String name) throws TFormerException
	Removes the DSFieldMapping from the DataSource. More...

void	removeParameter (DataSourceParameter parameter) throws TFormerException
	Removes the DataSourceParameter from the DataSource. More...

void	removeParameter (String name) throws TFormerException
	Removes the DataSourceParameter from the DataSource. More...

void	setComment (String sComment) throws TFormerException
	Sets the comment for the DataSource. More...

void	setCopyColumnName (String sCopyColumnName) throws TFormerException
	Sets the CopyColumnName of the DataSource. More...

void	setDescription (String sDescription) throws TFormerException
	Sets the description of the DataSource. More...

void	setHandleEscapeSequences (boolean bEscapeSequences) throws TFormerException
	Sets if escape sequences should be translated on data retrieval or not. More...

void	setName (String sName) throws TFormerException
	Sets the name of the DataSource. More...

String	toString ()
	Returns a string representation of the instance. More...

Detailed Description

Abstract class for a DataSource.

Overview

TFORMer Designer allows to define a DataSource as part of a FormLayout. Such an user-defined DataSource can be used for printing directly from within TFORmer Designer or may be re-used by TFORmer SDK for providing JobData (see JobDataDataSource).

A DataSource defines how data is retrieved (e.g. from an ODBC database), the field-mappings (see DSFieldMapping), computed fields (see ComputedField) and optional data source parameters (see DataSourceParameter). Each DataSource is identified by its unique name. Optional DataSourceParameters can be defined to control certain aspects (like filenames, SQL statement or an ODBC-DSN) during runtime.

By default TFORMer Designer creates a DataSource named _Default_. This DataSource is used for printing as long as neither a DataSource is specified for JobData nor the FormLayout has an active DataSource set in design. This DataSource retrieves the data from the file that is stored along with the FormLayout file (extension .xml) and contains the DataField values entered during the last TFORMer Designer session.

The available DataSource-classes are DataSourceCsv, DataSourceOdbc and DataSourceXml.

Escape Sequences

It depends on setHandleEscapeSequences whether possible escape sequences in the values are translated into their corresponding binary representation. See Escape Sequences for details.

Record Copies

Each Record of a DataSource is usually considered exactly once for generating output. Use DataSource.setCopyColumnName to instruct TFORMer SDK to use a specific field of the DataSource which contains the copy counter. This feature is helpful whenever a single Record of a DataSource should be printed multiple times (e.g. if a certain number of identical labels should be printed).

Computed Fields

Computations can be centralized in the DataSource instead of performing the computations in the FormLayout. The result of a ComputedField is available in the DataSource like any other source-field.

Example

Sample code that iterates all DataSource of a given Repository:

static void IterateDataSourcesProject (Project project) throws TFormerException
{
  // Iterate all DataSources of the Project
  for (DataSource ds = project.getFirstDataSource(); ds != null; ds = ds.getNext())
  {
    System.out.println (ds.toString());
    // Print information for the DataSourceParameters of the DataSource
    for (DataSourceParameter dsParam = ds.getFirstParameter(); dsParam != null; dsParam = dsParam.getNext())
      System.out.println (dsParam.toString());
    // Print information for the ComputedFields of the DataSource
    for (ComputedField dsComp = ds.getFirstComputedField(); dsComp != null; dsComp = dsComp.getNext())
      System.out.println (dsComp.toString());
    // Print the mapping between source fields and DataFields
    for (DSFieldMapping dsFieldmap = ds.getFirstDSFieldMapping(); dsFieldmap != null; dsFieldmap = dsFieldmap.getNext())
      System.out.println (dsFieldmap.toString());
  }
}

  // Create a new Repository instance using a Repository (extension *.tfr)
  // Examples are usually installed in
  // - Windows Vista: C:/Program Data/TEC-IT/TFORMer/7.5/Examples
  // - Older Microsoft Windows versions: C:/Documents and Settings/All Users/Application Data/TEC-IT/TFORMer/7.5/Examples
  Repository repository = new Repository("C:/Documents and Settings/All Users/Application Data/TEC-IT/TFORMer/7.5/Examples/Demo Repository/Demos.tfr", false, true);

  // Iterate the DataSources of the global Project
  // If a Repository is used, the global Project and additional user-defined Projects may exist
  System.out.println ("Global project");
  IterateDataSourcesProject (repository.getGlobalProject ());
  // Iterate additional Projects
  // Additional Projects are only possible when using a Repository
  for (Project project = repository.getFirstProject (); project != null; project = project.getNext()) 
  {
    System.out.println (project.toString());
    // Iterate the DataSources of the Project
    IterateDataSourcesProject (project);    
  } 

Sample code that iterates all DataSource-objects of a given stand-alone FormLayout:

static void IterateDataSourcesProject (Project project) throws TFormerException
{
  // Iterate all DataSources of the Project
  for (DataSource ds = project.getFirstDataSource(); ds != null; ds = ds.getNext())
  {
    System.out.println (ds.toString());
    // Print information for the DataSourceParameters of the DataSource
    for (DataSourceParameter dsParam = ds.getFirstParameter(); dsParam != null; dsParam = dsParam.getNext())
      System.out.println (dsParam.toString());
    // Print information for the ComputedFields of the DataSource
    for (ComputedField dsComp = ds.getFirstComputedField(); dsComp != null; dsComp = dsComp.getNext())
      System.out.println (dsComp.toString());
    // Print the mapping between source fields and DataFields
    for (DSFieldMapping dsFieldmap = ds.getFirstDSFieldMapping(); dsFieldmap != null; dsFieldmap = dsFieldmap.getNext())
      System.out.println (dsFieldmap.toString());
  }
}

  // Create a new Repository instance using a stand-alone FormLayout (extension *.tff)
  // Examples are usually installed in
  // - Windows Vista or later: C:/Program Data/TEC-IT/TFORMer/7.5/Examples
  // - Older Microsoft Windows versions: C:/Documents and Settings/All Users/Application Data/TEC-IT/TFORMer/7.5/Examples
  Repository repository = new Repository("C:/Documents and Settings/All Users/Application Data/TEC-IT/TFORMer/7.5/Examples/Command Line/ODBCReportPDF/ODBCReportPDF.tff", false, true);

  // Iterate the DataSources of the global Project
  // If a stand-alone FormLayout is used, the global Project is the only Project
  System.out.println ("Global project");  
  IterateDataSourcesProject (repository.getGlobalProject ());  

More Information

See also: ComputedField

Member Function Documentation

ComputedField addComputedField ( String name ) throws TFormerException

Creates and adds a ComputedField to the DataSource.

Parameters

name	The name of the ComputedField

Returns: A new ComputedField

See also: ComputedField

DSFieldMapping addFieldMapping ( String name ) throws TFormerException

Creates and adds a DSFieldMapping to the DataSource.

Parameters

name	The name of the DataField for which a DSFieldMapping should be created.

Returns: A new DSFieldMapping

DataSourceParameter addParameter ( String name ) throws TFormerException

Creates and adds a DataSourceParameter to the DataSource.

Parameters

name	The name of the DataSourceParameter

Returns: A new DataSourceParameter

See also: DataSourceParameter

void dispose ( ) throws TFormerException

Releases the resources allocated by the instance.

Call this method in every case (even in case of exceptions) is this instance is not required anymore.

void dump ( PrintStream s ) throws IOException, TFormerException

Dumps the current instance into a text stream.

Parameters

s	Instance of the stream

String getComment ( ) throws TFormerException

Gets the comment for the DataSource.

Returns: The comment for the DataSource

ComputedField getComputedField ( String name ) throws TFormerException

Gets a ComputedField defined in the DataSource.

Parameters

name	The name of the ComputedField

Returns: A valid object instance or null

See also: ComputedField

String getCopyColumnName ( ) throws TFormerException

Gets the CopyColumnName of the DataSource.

Returns: The CopyColumnName of the DataSource

See also: DataSource

String getDescription ( ) throws TFormerException

Gets the description of the DataSource.

Returns: The description of the DataSource

DSFieldMapping getFieldMapping ( String name ) throws TFormerException

Gets a DSFieldMapping defined in the DataSource.

Retrieves the DSFieldMapping for a given DataField name from the DataSource

Parameters

name	The name of a DataField

Returns: A valid object instance or null

ComputedField getFirstComputedField ( ) throws TFormerException

Gets the first ComputedField defined in the DataSource.

Returns: The first ComputedField object in the list or null

See also: ComputedField

DSFieldMapping getFirstDSFieldMapping ( ) throws TFormerException

Gets the first DSFieldMapping defined in the DataSource.

Returns: The first DSFieldMapping in the list or null

DataSourceParameter getFirstParameter ( ) throws TFormerException

Gets the first DataSourceParameter defined in the DataSource.

Returns: The first DataSourceParameter defined in the DataSource or null

See also: DataSourceParameter

String getName ( ) throws TFormerException

Gets the name of the DataSource.

Returns: The name of the DataSource

DataSource getNext ( ) throws TFormerException

Gets the next DataSource instance defined in the Project.

A Project stores a list of DataSource objects. To retrieve the first DataSource in the Project see Project.getFirstDataSource.

Returns: null if there aren't other instances in the Project, otherwise a valid instance of this class (DataSourceCsv, DataSourceOdbc or DataSourceXml)