J2PrinterPDFTest Document
Wildcrest Associates
http://www.wildcrest.com
February 9, 2009
 

  Abstract
This document is designed for testing the J2PrinterWorks Java 2 printing component from Wildcrest Associates. In particular, it will illustrate the use of the print-to-PDF, display-PDF-file, and print-PDF-file capabilities of the J2PrinterWorks J2Printer printing class.

PDF printing
Although J2PrinterWorks normally prints documents to actual printers, it can also print the equivalent document directly to a PDF file. The resulting PDF file can be viewed or printed later using programs such as Adobe Acrobat Reader, and the resulting document should look the same as the printed version.

J2Printer methods that perform the print-to-PDF, display-PDF-file, and print-PDF-file functions are: The fileNames can either be relative to the application working directory or may be specified using an absolute path. If fileName is null or the empty string, the file name will be assumed to be out.pdf. If fileName has no extension, the extension .pdf will be added to the specified file name.

Test program buttons
The J2PrinterPDFTest program provides five buttons to control its various functions:
Button Function
Read .HTML file Opens a file dialog, read .html file into display window
Print Preview Opens the standard J2PrinterWorks print preview dialog
Print to PDF File
 Prompts for a file name and calls the method printToPDF(fileName")
Display PDF File Prompts for a file name and calls the method displayPDFFile(fileName")
Print PDF File Prompts for a file name and calls the method printToPDF(fileName")


Required JDK and other software
The J2PrinterWorks print-to-PDF capability works under any JDK (as opposed to the J2PrinterWorks printToPS capability which requires the class J2Printer14 and therfore requires JDK 1.4 or later.

The J2PrinterWorks printToPDF method requires the presence of the free, open source, third-party component iText.jar, available under LGPL and MPL licenses from http://www.lowagie.com/iText.  Download the latest version of the component and place it in your classpath, such as in the same folder as the J2PrinterPDFTest program.

The J2PrinterWorks displayPDFFile and printPDFFile methods require that Adobe Acrobat Reader (or Adobe Acrobat) be installed on the user's machine.  In addition, since these methods work by invoking Adobe Acrobat Reader as an external program (using the Java "exec" capability), and use Windows-based command line syntax, these methods may not work under all operating systems.

Sample code
The following code sample illustrates how to use J2PrinterWorks to print any Pageable document to a PDF file:
J2Printer printer = new J2Printer();
J2TextPrinter textPrinter = new J2TextPrinter(yourJTextPane);
printer.addPageable(textPrinter);
printer.setLeftMargin(.25);
printer.setRightMargin(.25);
printer.setTopMargin(.25);
printer.setBottomMargin(.25);
printer.printToPS("printout.pdf");

Note in the code sample above, the four margins are set explicitly. Since, unlike regular printers, the PDF targets have no physical margin limitations, they can print right up to the edge of any page. As a result, the default margins for printToPDF printing are, in effect, 0.0 on all four sides. Thus, if you want to make your document look more like a conventional printed page, set the margins to appropriate non-zero values as shown above.

Additional considerations
An alternative to using printToPDF is to use the J2PrinterWorks printToPS method, available under J2Printer14 and requiring JDK 1.4 or later, to print to a Postscript (".ps") file, then use programs such as Adobe Distiller or Ghostscript (PS2PDF) to convert your .ps file to a .pdf. We find that .ps files are about twice the size of the equivalent .pdf file.

The printToPDF method honors the current setting of setSeparatePrintThread(boolean), just like the regular J2Printer print method. Therefore, by default, printToPDF returns immediately and the actual printToPDF operations are carried out asynchronously in a separate thread. If you wish to have printToPDF execute from your calling thread and not return until printing to the file is complete, call setSeparatePrintThread(false) in advance of your call to printToPDF. Also, the full set of J2PrinterWorks print progress events are fired during the execution of printToPDF, so that if printToPDF executes asynchronously, your UI thread can receive print progress events and provide a progress report to the user.

By default the printPDFFile(method) prints to the default printer on the user's machine.  If you wish to specify a different printer, you can do this programmatically using the J2Printer14 class, which requires using JDK 1.4 or later.  You can use the J2Printer14 method getPrinterNames to discover the list of available printers, and then use the method setPrinter to specify a particular printer for subsequent printing.  Here's some sample code that illustrates this technique:
J2Printer14 printer = new J2Printer14();
String[] printers = printer.getPrinterNames(); // find all printier names
printer.setPrinter(printers[i]);               // specify some printer "i"
printer.printPDFFile("file.pdf");              // print existing "file.pdf"

In the above scenario, you might create a dialog to allow the user to select from among the available printers. Or, if you know the name of the desired printer, you can simply call setPrinter directly. The printer selection capabilities of J2Printer14, allowing you to request the names of just those printers with particular properties, are also available.

Since most printers have non-zero minimum physical margins, the current printer choice will impose these minimum margins on your document when using printToPDF even if you call setLeftMargin(0.0), etc.  If you wish to printToPDF with actual zero margins, the easiest way is to print using a PrinterJob whose virtual printer does not impose non-zero minimum margins.  The following code will accomplish this:

public class MyPrinterJob extends sun.awt.windows.WPrinterJob {            
     public MyPrinterJob() { super();}
     public PageFormat validatePage(PageFormat pageFormat) {
          return pageFormat;  }    // return page format unchanged
}
...
printer = new J2Printer("your-serial-number", new MyPrinterJob());