jPDFPrint Developer Guide
jPDFPrint Developer Guide
jPDFPrint is a Java library that can be used to print PDF files without the need to install any third party programs or drivers. jPDFPrint can print PDF files silently as well as with user interaction. jPDFPrint integrates easily into applications, applet, J2EE application servers or any other server environment and delivers the most features, performance and reliability of any Java PDF printing library.
With jPDFPrint, your application or server can print PDF documents automatically and efficiently from local files, URL’s and even Java input streams. This allows you to print documents that are created runtime or that are served from web servers or database servers.
jPDFPrint is built around a main object, com.qoppa.pdfPrint.PDFPrint that provides printing functions. To print a PDF file, the host application will typically create a new instance of the object and then tell the object to print. In the simplest case, only two lines are needed to print a PDF file:
PDFPrint pdfPrint = new PDFPrint (fileName, null); pdfPrint.print (new PrintSettings ());
In this example, the PDFPrint constructor takes two parameters, a file name and an object that implements IPasswordHandler. The IPasswordHandler interface is used to retrieve a password when a PDF document is encrypted. This parameter can be null if the PDF files are not encrypted. There are also constructors for the PDFPrint object that take a URL or an InputStream as the first parameter.
The second line of the sample tells PDFPrint to print the document by showing the print dialog and using the default print settings. There are also methods to print the document silently (without a printer dialog) and using different printer settings.
jPDFPrint provides the ability to print PDF documents without showing the printer dialog or any other user intervention. This is implemented by providing a version of its print method that takes a printer name as its first parameter:
PDFPrint.print (String printerName, PrintSettings printSettings)
By passing the name of the printer to this method, the library will print directly to that printer without showing the user a printer dialog. If the calling application passes null for the printer name, the library will print to the default printer. So, to print to a named printer, the previous sample would be changed to:
PDFPrint pdfPrint = new PDFPrint (fileName, null); pdfPrint.print ("myprinter", new PrintSettings ());
When printing with jPDFPrint, the printing methods take a PrintSettings object as a parameter. This parameter is used to control the way that jPDFPrint will print each page. The object has several properties that can be set by the calling application:
- AutoRotate – This setting tells PDFPrint to detect the orientation of the PDF document and to print appropriately to the printer page. i.e. If the document is in landscape mode, the library will send it to the printer in that mode. Setting this to false will always use portrait mode when sending to the printer.
- ShrinkToMargins – This setting tells PDFPrint to shrink the page to fit within the printer’s margin if the document page is larger than the printer page. This option has no effect if the document page is smaller than the printer page.
- ExpandToMargins – This setting tells PDFPrint to expand the page to fit within the printer’s margin if the document page is smaller that the printer page. This option has no effect if the document page is larger than the printer page.
- CenterInPage – This setting tells PDFPrint to center the page within the printer’s page. This option only has an effect when the document page is smaller than the printer page and the ExpandToMargins option is set to false.
When a PrintSettings object is created using its default constructor, the default settings are:
- AutoRotate = true
- ShrinkToMargins = true
- ExpandToMargins = false
- CenterInPage = true
Printable / Pageable
In addition to providing print methods, for added flexibility, PDFPrint implements both the Printable and Pageable interfaces. By using PDFPrint in this manner, the calling application can create its own PrinterJob, set any options that it needs to, and then set PDFPrint as the job’s Printable or Pageable object.
This can be useful when the application needs to use print request attributes (javax.print.attribute.PrintRequestAttribute) for finer control of printing options such as choosing the paper size or media tray, printing in color and others.
The PDFPrint object implements Printable directly, so it can be used with a PrinterJob as follows:
PDFPrint pdfPrint = new PDFPrint (fileName, null); PrinterJob pJob = PrinterJob.getPrinterJob(); pJob.setPrintable (pdfPrint); HashPrintRequestAttributeSet printAttrSet = new HashPrintRequestAttributeSet (Chromaticity.COLOR); pJob.print(printAttrSet);
Using PDFPrint as a Pageable in a PrinterJob is as follows:
PDFPrint pdfPrint = new PDFPrint (fiileName, null); PrinterJob pJob = PrinterJob.getPrinterJob(); pJob.setPageable (pdfPrint.getPageable (pJob)); HashPrintRequestAttributeSet printAttrSet = new HashPrintRequestAttributeSet (Chromaticity.COLOR); pJob.print(printAttrSet);
Distribution and JAR Files
Only the jPDFPrint.jar file is always required for deployment, the remaining jar files are used to work with specific features in some PDF documents:
jPDFPrint.jar – This is the main jar file for the component, it is always required.
cmykProfile.jar – This jar file contains a CMYK profile used to accurately convert CMYK colors to RGB for printing. If the file is not present, jPDFPrint will revert to a mathematical conversion that is less accurate. This file is necessary if the PDF documents viewed have CMYK content and accurate color conversion is desired.
cmaps.jar – This jar file contains CMaps, used to read and display character encodings used with CJK (Chinese, Japanese, Korean) content.
jai_imageio.jar – This jar file contains Java’s ImageIO image decoders, including a decoder for JPEG 2000 images. This is only used when a document contains JPEG 2000 images.