jPDFPrint Entwicklerhandbuch

Contents
Einführung
Erste Schritte
Sofort / Direktdruck
Drucker-Einstellungen
Printable / Pageable
Verteilung und JAR-Dateien
Javadoc API

Einführung

jPDFPrint ist eine Java-Bibliothek, mit der man PDF-Dateien drucken kann, ohne Programme von Drittherstellern oder Treiber installieren zu müssen. jPDFPrint kann PDF-Dateien direkt, aber auch mit Benutzer-Interaktion, drucken. jPDFPrint integriert sich leicht in Anwendungen, J2EE-Anwendungs-Server oder andere Server-Umgebungen und bietet die meisten Features, beste Performance und höchste Zuverlässigkeit als jede andere Java-PDF-Druck-Bibliothek.

Mit jPDFPrint kann Ihre Anwendung oder Server PDF-Dokumente automatisch und effizient von lokalen Dateien, URLs oder gar Java Input-Streams drucken. Dies erlaubt Ihnen Dokumente zu drucken, die zur Laufzeit angelegt oder in Webservern oder Datenbank-Servern vorgehalten werden.

Erste Schritte

jPDFPrint ist rund um das Wurzelobjekt com.qoppa.pdfPrint.PDFPrint aufgebaut, dieses stellt Druck-Funktionen zur Verfügung. Um eine PDF-Datei zu drucken, wird die Host-Anwendung typischerweise eine neue Instanz dieses Objekt anlegen und ihm mitteilen, einen Druck durchzuführen. Im einfachsten Fall, werden nur zwei Codezeilen benötigt, um eine PDF-Datei zu drucken:

PDFPrint pdfPrint = new PDFPrint (fileName, null);
pdfPrint.print (new PrintSettings ());

In diesem Beispiel übergibt man dem PDFPrint-Konstruktor zwei Parameter, einen Dateinamen und ein Objekt, das IPasswordHandler implementiert. Das IPasswordHandler-Interface wird benötigt, um ein Kennwort abzufragen, falls das PDF-Dokument verschlüsselt ist. Dieser Parameter kann “null” sein, falls die PDF-Dateien nicht verschlüsselt sind. Es gibt auch Konstruktoren für das PDFPrint-Objekt, denen man eine URL oder einen InputStream als ersten Parameter übergeben kann.

Die zweite Zeile des Beispiels teilt PDFPrint mit, das Dokument über einen Druck-Dialog und den standardmäßigen Druck-Einstellungen zu drucken. Es gibt auch Methoden, um das Dokument direkt/sofort (ohne einen Druck-Dialog) mit verschiedenen Drucker-Einstellungen auszudrucken.

Sofort / Direktdruck

jPDFPrint besitzt die Fähigkeit, PDF-Dokumente ohne Anzeige eines Druck-Dialogs oder irgendeine Benutzer-Interaktion zu drucken. Dies wird über eine Version seiner Print-Methode umgesetzt, die einen Drucker-Namen als ersten Parameter verlangt:

PDFPrint.print (String printerName, PrintSettings printSettings)

Wird dieser Methode der Drucker-Name übergeben, wird die Bibliothek unmittelbar auf diesem Drucker ausgeben, ohne dem Benutzer einen Druck-Dialog anzuzeigen. Falls die aufrufende Anwendungen als Drucker-Name “null” übergibt, wird die Bibliothek auf dem Standard-Drucker ausgeben. Um auf einen benannten Drucker auszugeben, wird das vorherige Beispiel wie folgt geändert:

PDFPrint pdfPrint = new PDFPrint (fileName, null);
pdfPrint.print ("myprinter", new PrintSettings ());

Drucker-Einstellungen

Beim Ausdrucken mit jPDFPrint, übergibt man den Druck-Methoden ein PrintSettings-Objekt als Parameter. Dieser Parameter wird gebraucht, um die Art und Weise zu kontrollieren, mit der jPDFPrint jede Seite ausdruckt. Das Objekt hat verschiedene Attribute, die durch die aufrufende Anwendung gesetzt werden können:

• AutoRotate – Diese Einstellung teilt PDFPrint mit, die Ausrichtung des PDF-Dokuments festzustellen und passend auf der Druckseite auszudrucken. Befindet sich das Dokument z. B. im Querformat, schickt die Bibliothek es in diesem Format an den Drucker. Wird diese auf “false” gesetzt, so wird immer das Hochformat beim Druck auf dem Drucker verwendet.
• ShrinkToMargins – Diese Einstellung teilt PDFPrint mit, die Seite innerhalb der Grenzen des Druckers passend zu verkleinern, sollte die Dokumentseite größer als die Druckseite sein. Diese Option hat keine Auswirkung, falls die Dokumentseite kleiner als die Druckseite sein sollte.
• ExpandToMargins – Diese Einstellung teilt PDFPrint mit, die Seite innerhalb der Grenzen des Druckers passend zu vergrößern, sollte die Dokumentseite kleiner als die Druckseite sein. Diese Option hat keine Auswirkung, falls die Dokumentseite größer als die Druckseite sein sollte.
• CenterInPage – Diese Einstellung teilt PDFPrint mit, die Seite innerhalb der Grenzen des Druckers zu zentrieren. Diese Option hat nur eine Auswirkung, falls die Dokumentseite kleiner als die Druckseite sein sollte und die ExpandToMargins-Option auf “false” gesetzt wurde.

Wenn ein PrintSettings-Objekt durch seinen standardmäßigen Konstruktor angelegt wird, sind die Default-Einstellungen wie folgt:

• AutoRotate = true
• ShrinkToMargins = true
• ExpandToMargins = false
• CenterInMargins = true

Printable / Pageable

Zusätzlich zu den Print-Methoden, implementiert PDFPrint für eine höhere Flexibilität die beiden Interfaces Printable und Pageable. Wird PDFPrint in diesem Sinne gebraucht, kann die aufrufende Anwendung ihren eigenen PrintJob erzeugen, die gewünschten Optionen setzen und dann PDFPrint als Printable- oder Pageable-Objekt des Jobs setzen.

Dies kann nützlich sein, wenn die Anwendung Print-Request-Eigenschaften (javax.print.attribute.PrintRequestAttribute) für eine feinere Kontrolle der Druck-Optionen wie Auswahl der Papiergröße, des Papierschachts, Drucken in Farbe und andere, benötigt.

Das PDFPrint-Objekt implementiert Printable direkt, so dass es mit einem PrinterJob wie folgt verwendet werden kann:

PDFPrint pdfPrint = new PDFPrint (fileName, null);
PrinterJob pJob = PrinterJob.getPrinterJob();
 
pJob.setPrintable (pdfPrint);
 
HashPrintRequestAttributeSet printAttrSet = new HashPrintRequestAttributeSet (Chromaticity.COLOR);
 
pJob.print(printAttrSet);

PDFPrint als ein Pageable innerhalb eines PrinterJob kann wie folgt verwendet werden:

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

jPDFPrint wird vollständig in einer einzigen JAR-Datei ausgeliefert; jPDFPrint.jar, diese wird mit dem Evaluationsbeispiel installiert. Wenn eine Anwendung, die jPDFPrint enthält, verteilt werden soll, muss, damit die Anwendung läuft, die jPDFPrint.jar-Datei zusammen mit ihr verteilt und in den Classpath aufgenommen werden.

Um JPEG 2000-Bilder zu unterstützen, verwendet jPDFPrint die Java Advanced Imaging (JAI)-Klassen. Da dieses API nur für Java 1.4.2 verfügbar ist, benötigt jPDFPrint Java 1.4.2 oder höher, falls man mit PDF-Dokumenten arbeitet, die JPEG2000-Bilder enthalten. Das API kann getrennt auf der Zielmaschine installiert werden oder die jai_imageio.jar-Datei (in der Installation des Beispielprogramms enthalten) kann unabhängig davon installiert und in den Classpath aufgenommen werden.