J2Printer14

J2Printer14

The class J2Printer supports the original Java 2 printing model, available since JDK 1.2, which uses the native OS printing and page setup dialogs. Under the original Java 2 printing model, the end user must specify in the print dialog the printer to be used (they will get the default printer for their machine if no print dialog is used).  That is, you the programmer cannot specify the printer (or discover the available printers) programmatically.  Also, only a limited set of printing values can be specified programmatically, e.g., orientation, number of copies, print job name, and paper size.  The primary virtue of restricting yourself to this model is that you can build and run software using the J2Printer class under any JDK 1.2.x or later.

The JDK 1.4 release introduced a new Java 2 printing model which extends Java printing capabilities to include support for printer discovery, programmatic printer selection, cross-platform page setup and print dialogs, and a full range of programmable print request attribute sets. J2PrinterWorks provides a special subclass of J2Printer called J2Printer14 which supports these additional capabilities.  The primarily limitation of using J2Printer14 is that you must use JDK 1.4 or later to build and run software that uses the J2Printer14 class .  To begin fully utilizing the JDK 1.4+ capabilities, you simply change the constructor in the above code samples to:

    J2Printer14 printer = new J2Printer14();

Since J2Printer14 is a J2Printer subclass, all of the J2Printer methods described in the preceding sections can still be used.
 

Print request attribute sets

Under the JDK 1.4+ printing model, you can specify a broad range of desired print features and characteristics using a PrintRequestAttributeSet and pass these to your J2Printer14 instance to control printing using the method setPrintRequestAttributeSet.  The following example shows how this is done:

    J2Printer14 printer = new J2Printer14();
    PrintRequestAttributeSet aset = new HashPrintRequestAttributeSet();
    aset.add(new Copies(2));
    aset.add(new JobName("My print job name", null));
    aset.add(MediaSizeName.ISO_A4); // or MediaSizeName.NA_LETTER, MediaSizeName.NA_LEGAL, etc.
    aset.add(OrientationRequested.LANDSCAPE);
    aset.add(new PageRanges(1,printer.getPageable().getNumberOfPages()));
    aset.add(PrintQuality.DRAFT);
    aset.add(Chromaticity.MONOCHROME);
    printer.setPrintRequestAttributeSet(aset);

See the JDK 1.4+ class PrintRequestAttributeSet for the complete list of print attributes that may be specified.  The values you specify with a PrintRequestAttributeSet will be used in initializing both the page setup and print dialogs.  The values may be modified or ignored by the underlying system in displaying the page setup and print dialogs depending on the capabilities of the current printer.  The end user may further modify the choices presented to them in the page setup and print dialogs to arrive at the settings actually used in printing. The internal value actually used in printing (and returned by the J2Printer14 method getPrintRequestAttributeSet ) will automatically be updated to reflect these modifications.

You can still use the J2Printer methods setNumberOfCopies, setPrintJobName, setPaperSize, setOrientation, setPageFormat, and the four methods for setting margins setLeftMargin, setRightMargin, setTopMargin, and setBottomMargin. The values set by these methods will update the values set by your most recent call to setPrintRequestAttributeSet to determine the values used in the page setup and print dialogs.  Likewise, when you call setPrintRequestAttributeSet and specify any of the same attributes, these values will be used to update the J2Printer method values.  Thus, you can use and intermix calls with either the J2Printer API or the PrintRequestAttributeSet API and the most recent versions of all the values will be used.  Note, however, that attributes such as PageRanges that do not have corresponding "set" methods are not supported by Java for the native print dialogs and will only work when using the cross-platform print dialogs (this is true even if you have called setPrintDialogUsed(false)).

NOTE: On the Macintosh under the current JDK 1.5.0_16, the PageRanges attribute does not work properly.  The specified values are displayed, but the entire page range is always printed.  A bug report for this problem has been filed with Apple.  Until it is fixed, we recommend using the native Mac print dialog which works correctly.
 

Cross-platform dialogs

The J2Printer14 method setCrossPlatformDialogs is used to control whether the native OS page setup and print dialogs or the cross-platform page setup and print dialogs are used.

setCrossPlatformDialogs (boolean crossPlatformDialogs)
          Sets whether to use the cross-platform printing dialogs instead of the native printing dialogs.  

Print dialog

With setCrossPlatformDialogs(true) in effect (which is the default for J2Printer14), the Java cross-platform print dialog is displayed when the J2Printer14 method print() is called.  This dialog allows the user to control printer selection, page range, number of copies, etc. and in addition has separate tabs for Page Setup (orientation, margins, paper size), and Appearance (color, quality, etc.).   The Java cross-platform print dialog looks as follows:

If the J2Printer14 method setPrintDialogUsed(false) has been called, then no print dialog is shown when the print() method is called and instead J2PrinterWorks prints one copy of all pages on the default printer.

The J2PrinterWorks product distribution also includes the complete source code for two page setup dialogs.  One is the source code for a "SimplePageSetupDialog" which only permits choice of paper size, orientation, and margins.  A second is the source code for a "TabbedPrintDialog", comparable to the Java cross-platform print dialog, which has tabs for "Page Setup" (paper size, orientation, and margins) and "Headers/Footers" (left/center/right headers and footers).  Either of these page setup dialogs may be customized by developers to create a page setup dialog with the features and appearance of their choosing.  See the documentation section entitled "Custom Print, Page Setup, and Print Preview dialogs".

NOTE: On the Macintosh under the current JDK 1.5.0_16, the cross-platform page setup dialog has the problem that the Orientation portion of the dialog always appears disabled so that users can only view and not change the specified setting.  A bug report for this problem has been filed with Apple.  Until it is fixed, we recommend using either the native Mac page setup dialog or one of the Wildcrest Associates page setup dialogs described above.

Printer discovery

J2Printer14 allows you to find the list of available printers for a given print job.  This is done using the following code:

    J2Printer14 printer = new J2Printer14();
    printer.setPrintRequestAttributeSet(yourAttributeSet);
    String[] printerNames = printer.getPrinterNames();

The getPrinterNames method returns an array of printer names that can support your specified PrintRequestAttributeSet.  If yourAttributeSet is null, all available printers are returned.  The available printers are all those known to the user's underlying OS, whether directly connected to the user's machine or available across the network, i.e., the same list that normally appears as the printer choices in a print dialog (NOTE: as of JDK 1.4.2, Apple does not yet support printer discovery on the Macintosh, so that if any PrintRequestAttributeSet is specified, the getPrinterNames() method will return no printer names).

You can find all available printers on your machine regardless of the current PrintRequestAttributeSet (including on the Macintosh) using the following method:

    String[] printerNames = printer.getAllPrinterNames();

You can determine the default printer on the user's machine using the method:

    String defaultPrinter = printer.getDefaultPrinterName();

Once you've determined the name of the printer you wish to use, J2Printer14 lets you specify this printer programmatically using the method:

    printer.setPrinter(printerName);

The value of printerName should be one of those returned by the method getPrinterNames, i.e., it should be one of the available printers given the current PrintRequestAttributeSet. If name does not match one of the available printers, the default printer is used.
 

Specifying PrinterJob

As an alternative to using the J2Printer14 methods to set up your PrintRequestAttributeSet and printer choice, you can use the Java PrinterJob and PrintRequestAttributeSet classes directly to define a desired java.awt.print.PrinterJob instance yourself, then pass this to J2Printer14 using the following method:

    printer.setPrinterJob(printerJob);

The setPrinterJob method is also supported by the J2Printer class but in that case only the PrinterJob attributes supported prior to JDK 1.4 are recognized, e.g., number of copies and print job name, and not the printer name or the extended print request attributes supported under JDK 1.4 or later.

Printing to a Postscript file

The J2Printer14 class provides methods that allow you to "print" your document to a Postscript file.  A method available for this purpose is:

printToPS(java.lang.String file)
          Utility method for printing the document to a Postscript (.ps) file, suitable for dumping to a Postscript printer (for example, on Windows use the DOS command copy /b filename.ps lpt1:  or a program like PrintFile, see http://www.lerup.com/printfile), viewing or printing on any device with a program such as Ghostscript (http://www.ghostscript.com), or converting to PDF using programs such as Adobe Acrobat Distiller or the PS2PDF (part of Ghostscript), see below.

The Postscript printing capability was first introduced by Java under JDK 1.4, so the printToPS method requires JDK 1.4 or later.  The file specification is relative to the working directory of the application.  If subfolders are specified, all must already exist, they will not be created for you.  If the file name is missing, the file name out.ps will be used.  If the extension is missing, the file extension .ps is added.

J2Printer14 also has convenience printToPS methods available for writing the Postscript output to an in-memory byte array or to a provided OutputStream.

The call to printToPS honors the setSeparatePrintThread(boolean) method, so that by default this method executes in a background thread and fires print progress events .  Call setSeparatePrintThread(false) in advance of calling this method if you don't want this method to return until printing completes.

NOTE: There currently appears to be a bug in the Java (JDK 1.5.0_16) on Mac OS X that prevents the printToPS method from working properly on the Mac for most Pageables containing formatted text, throwing an ArrayIndexOutOfBoundsException deep inside Java's glyph rendering code.  We have logged this problem report with Apple.  Until this problem is fixed, we recommend using  printToPDF (see next).

You can call the J2Printer method printToPDF(java.lang.String file) to save your document to a PDF file.  This feature does not require JDK 1.4 or J2Printer14, but it does require the presence of the free, third-party component iText.jar (see "printToPDF" in the J2Printer documentation).  

The call to printToPDF honors the setSeparatePrintThread(boolean) method, so that by default this method executes in a background thread and fires print progress events.  Call setSeparatePrintThread(false) in advance of calling this method if you don't want this method to return until printing completes.