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
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 JobName("My print job name", null));
aset.add(MediaSizeName.ISO_A4); // or MediaSizeName.NA_LETTER, MediaSizeName.NA_LEGAL, etc.
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
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.
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.
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 three print dialogs. One is the source code for a "SimplePrintDialog" which only permits choice of printer, page range, and number of copies. A second is the source code for a "TabbedPrintDialog", comparable to the Java cross-platform print dialog, which has tabs for "General" (printer selection, page range, and number of copies), "Page Setup" (paper size, orientation, and margins), and "Headers/Footers" (left/center/right headers and footers). The third is the source code for a "PreviewPrintDialog" which features the "General" controls, the "Page Setup" controls, and a print preview display, all in one single-pane dialog. Any of these print dialogs may be customized by developers to create a print dialog with the features and appearance of their choosing. See the documentation section entitled "Custom Print, Page Setup, and Print Preview dialogs".
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.
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();
String printerNames = printer.getPrinterNames();
The getPrinterNames method returns an array of printer
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
String printerNames =
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:
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
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:
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.
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:
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
The call to printToPDF honors
the setSeparatePrintThread(boolean) method, so that by default this
method executes in a background thread and fires print progress
setSeparatePrintThread(false) in advance of calling this method if you
don't want this method to return until printing completes.