TFORMer SDK - JAVA  8
Basic Concept / Printing

Installation

Install TFORMer Designer (the graphical layout editor) and TFORMer SDK (the reporting and label printing core) using the setup applications. TFORMer SDK is available as DLL, as COM component, as .NET assembly, as JAVA class and as stand-alone application (TFPrint). Both the COM component and the .NET assembly of TFORMer SDK are registered automatically. The .NET assembly is automatically placed in the GAC and in the Bin directory of the installation folder. The Java package JTFORMer8.jar (which is compatible with the Java Runtime Edition - JRE version 1.5 or higher) is copied into the Bin directory: It includes all classes that you need to create a TFORMer application with the Java language.

Design a FormLayout

Use TFORMer Designer to create a FormLayout graphically. Most likely a FormLayout contains dynamic data which will be provided by your application during print-time (e.g. an article number for a product label or a ticket number for an e-ticket). TFORMer uses DataFields as place-holders for such dynamic data. These DataFields are declared as well as used within the FormLayout.

Check out the following paragraphs to learn how to print or export a FormLayout with data provided by your application!

Create a Java Project

Create a new Java project or at least a new Java source file.

Link your application with the JTFORMer8.jar (the TFORMer package). To do so, either use the classpath list in your IDE or use java -cp %CLASSPATH%

For creating a Java program with the TFORMer Java API, you need to import a few TFORMer Packages:

  import com.tecit.TFORMer.*;                   // Licensing, Error handling, Enumerations
  import com.tecit.TFORMer.Repository.*;        // Provides access to Repository elements 
  import com.tecit.TFORMer.Printing.*;          // Contains functionality for a Print-Job
  import com.tecit.TFORMer.Enumerations.*;      // Contains all enumerations

License and Initialize TFORMer SDK

Licensing is not required for evaluation purposes. For production, apply a license key to TFORMer SDK before using any other properties or methods of TFORMer. This needs to be done only once, for example when initializing the application.

  TFORMer.license("John Doe", ELicenseKind.Workstation, 1, "00000000000000000000000000000000"); 

Select the FormLayout to be Used

Printing is done with the help of a print Job. Create a Job and select the FormLayout by setting the appropriate properties.

  // Create a new Job instance
  Job printJob = new Job();
  // Select the stand-alone FormLayout
  printJob.setRepositoryName ("C:/Users/All Users/TEC-IT/TFORMer/8/Examples/Command Line/ODBCReportPDF/ODBCReportPDF.tff");
Note:
TFORMer Designer supports so-called stand-alone FormLayouts (which are created by default by TFORMer Designer) and Repository based FormLayouts (which enable you to organize a large number of FormLayouts in a structured way). Check out Repository / FormLayout for details.

Whenever properties or methods are requesting input files (e.g. FormLayouts, or file-based DataSources like XML or CSV files), these may be passed as usual via the filename or by using BASE64 encoded strings. In addition, files and BASE64 strings may be zipped to save bandwidth. Refer to Passing Files for details.

Provide JobData

As mentioned above a FormLayout usually contains DataFields which are used as place holders for dynamic data. Before printing a FormLayout you need to provide data for these DataFields by assigning suitable JobData to the Job. Various methods are available for providing JobData.

Note:
The field names available in the JobData (e.g. the column names returned by a SQL-SELECT statement or the column names in a CSV file) must match the names of the DataFields used in a FormLayout. When using user-defined data sources (see user-defined data source below) the mapping between fields in the DataSource to DataFields in the FormLayout can be adjusted freely.

Provide JobData via Program Code

This is the most direct method to pass data to TFORMer SDK. In this case the names and values of the DataFields used in a FormLayout are provided directly. The example below sets the values for the DataFields ArticleNo, ArticleName and ArticlePrice.

  // Create a new JobData instance. 
  // Here we are using the JobDataRecordSet which accepts Records containing name/value pairs
  JobDataRecordSet jobData = new JobDataRecordSet();

  // Create a new Record
  JobDataRecordSet.Record record = new JobDataRecordSet.Record();
  // Add some name/value pairs for the DataField values to the Record
  record.setData("ArticleName", "Speaker System HF1");
  record.setData("ArticleNo", "12001234");
  record.setData("ArticlePrice", "498.98");
  // Add the Record to the JobData
  jobData.add(record);

  // Create a second Record
  record = new JobDataRecordSet.Record();
  // This Record should be printed two times
  record.setNumberOfCopies(2);
  record.setData("ArticleName", "Record Box 12 CDs");
  record.setData("ArticleNo", "12021231");
  record.setData("ArticlePrice", "8.85");
  jobData.add(record);

  // Assign the JobData to the Job
  printJob.setJobData(jobData); 

Load JobData From CSV Files

See also JobDataCsv

  // Create a new JobData instance. 
  // Here we import a CSV and specify separator and qualifier character
  JobDataCsv jobData = new JobDataCsv("path/data.csv", ',', '"');

  // Assign the JobData to the Job
  printJob.setJobData(jobData); 

Load JobData From XML Files

See also JobDataXml

  // Create a new JobData instance. 
  // Here we import a XML file (must comply with the supported XML schemes)
  JobDataXml jobData = new JobDataXml("path/data.xml");

  // Assign the JobData to the Job
  printJob.setJobData(jobData); 

Load JobData From a Database

See also JobDataOdbc

  // Create a new JobData instance
  // Here we import data from an ODBC connection using the specified SQL SELECT statement
  JobDataOdbc jobData = new JobDataOdbc(
    "DSN=TFORMer_Sample", 
    "", // Username
    "", // Password
    "SELECT * FROM tbl_Example"
  );

  // Assign the JobData to the Job
  printJob.setJobData(jobData); 

Load JobData From a User-Defined Data Source

See also JobDataDataSource

Last but not least TFORMer Designer offers the possibility to specify a "user-defined" DataSource as part of a FormLayout. Such a DataSource defines how data is retrieved (e.g. from an ODBC database) and it specifies the mappings between fields in the DataSource and DataFields in the FormLayout. If you want to use such a user-defined DataSource for JobData retrieval, select the DataSource by name as shown below. Use optional DataSourceParameters to control certain aspects (like the filename, SQL SELECT statement or DSN) of the DataSource during runtime.

  // Create a new JobDataDataSource instance
  // The DataSource named myTextDataSource must be defined in the FormLayout or Repository
  JobDataDataSource jobData = new JobDataDataSource ("myTextDataSource");

  // Set the DataSourceParameter named parFile
  jobData.setParameterValue ("parFile", "/YourPath/InputData.txt");

  // Assign the JobData to the Job
  printJob.setJobData(jobData); 

Generate Output

Print on a Printer

Use setPrinterName to specify the target printer. Provide an empty string, if you want to send the output to the default printer.

  // Select the printer name on Windows or Linux (CUPS printer name), use null for the default printer
  printJob.setPrinterName (null);   

  // Print
  printJob.print(); 

Export as PDF, PostScript, HTML, ZPL-II or as an Image

Instead of printing on a printer, you can export the output as a PDF, PostScript, HTML, ASCII or image file. ZPL-II (the ZEBRA printer language) generation is supported too. Instead of setting a printer name, set the name and type of the output file.

  // Select PDF output to /temp/out.pdf 
  printJob.setOutputName ("/temp/out.pdf");
  printJob.setPrinterType (EPrinterType.PDFFile);

  // Generate PDF
  printJob.print(); 

Generate Output as an In-Memory Stream

Starting with TFORMer version 7 it is possible to generate the output as an in-memory stream. No output or temporary files are required, the performance for creating the output is dramatically improved. Currently PDF- and image-output (excluding multi-page TIFF) are generated completely in-memory. If the output results in a single stream (this is true for Postscript, PDF, multi-page TIFF and ZPL output) use printToStream. If the generated output results in several streams (e.g. generating multiple labels as single PNG images) use printToStreams.

Use a Single Stream

  // Select PDF output 
  printJob.setPrinterType (EPrinterType.PDFFile);

  // Generate output using the streaming API (no temporary files will be needed on the file-system)
  // For demonstration purposes we provide a FileStream, a PDF file named /temp/out.pdf will be generated
  // In real life you will most likely use the stream to generate the response for some web-client
  OutputStream fos = new FileOutputStream("StreamToFileExample.pdf");

  // Generate PDF
  printJob.printToStream (fos);

Use Multiple Streams

  OutputStreamFactory factory = new OutputStreamFactory()
  {
    // Create a new stream 
    // This function will be called for each requested stream before any output is generated
    // You may use this function to open files or to reserve memory
    public OutputStream createOutputStream(String name)
    throws IOException
    {
      // For demonstration purposes we create a file stream
      return new FileOutputStream (name);
    }
  };
  // Generate a PNG image named StreamToFileExample.png
  // The provided OutputName is passed to CreateStream
  // If multiple pages are generated page numbers will get appended (e.g. StreamToFileExample_002.png)
  printJob.setOutputName  ("StreamToFileExample.png");
  printJob.setPrinterType (EPrinterType.ImagePng);

  // Generate output with the streaming API using the specified factory
  printJob.printToStreams (factory);  

Clean Up

The Java package invokes the API of TFORMer SDK via Java Native Interface (JNI). In order to free the resources allocated by TFORMer SDK, it's important to call the method dispose of the JTFormer classes. For this reason, you should always add the following code:

  // free resources used by TFORMer SDK
  printJob.dispose();
  // it's a good idea to set the variable to null, because the object is now invalid internally.
  printJob = null;
Note:
It's recommended to insert the source code that uses the Job instance into a try/catch block and insert the dispose procedure into the finally block. This ensures proper clean-up even in case of exceptions.
  Job printJob = new Job();
  try {
    // ... use the Job instance
  }
  catch(TFormerException ex){
    // ... manage the exception
  }
  finally {
    // free resources used by TFORMer SDK
    printJob.dispose();
    // it's a good idea to set the variable to null, because the object is now invalid internally.
    printJob = null;
  }

Execution & Runtime

The Java package invokes the API of TFORMer SDK via Java Native Interface (JNI). The API for Java is provided by the shared library TFORMer8JNI.dll (located in the Bin directory of the TFORMer SDK installation on Microsoft Windows) or libTFORMer8JNI.so (in /usr/local/lib on Linux/Unix platforms).
The Java virtual machine needs to be able to find the TFORMer native library: if the JVM can't resolve the TFORMer JNI API, the following exception is thrown:

  com.tecit.TFORMer.TFormerException: No JNITFORMer library found in java.library.path
    at com.tecit.TFORMer.JTFormerLibrary.<init>(JTFormerLibrary.java:62)
    at com.tecit.TFORMer.JTFormerLibrary.getInstance(JTFormerLibrary.java:31)
    at com.tecit.TFORMer.JNITFormer.<init>(JNITFormer.java:36)
    ...

To configure the JVM, you have to set the library path to the TFORMer JNI directory or copy the TFORMer shared libraries in your system library path. We suggest to set the library path

Note:
To learn more about building and executing the Java samples provided please refer to the README files which are installed with the Java projects. For more details, check out the official documentation about the JNI Technology.

More Information


© 2006-2024 - all rights reserved by TEC-IT Datenverarbeitung GmbH
Generated on Thu Oct 3 2024 05:08:23 for TFORMer SDK - JAVA with doxygen 1.7.6.1