Inhalt

Einführung
Erste Schritte
Mischen und Zerlegen
Auf einem Dokument zeichnen
Verschlüsselung und Berechtigungen
In Bilder exportieren
Ein Dokument drucken
Printable / Pageable
Mit Formularfeldern arbeiten
Innerhalb J2EE arbeiten
Verteilung und JAR-Dateien

Javadoc API
Source Code Samples

Einführung

jPDFProcess ist eine Java-Bibliothek mit der man PDF-Dokumente erzeugen, ändern und verarbeiten kann. Nach dem Bearbeiten eines Dokuments kann die Bibliothek das Dokument auf einem Dateisystem oder in einem Java-OutputStream speichern. Arbeitet man innerhalb eines J2EE-Anwendungs-Servers, so kann die Bibliothek innerhalb eines Servlets arbeiten, um veränderte PDF-Dokumente direkt in einem Browser auf dem Client anzuzeigen.

Die Bibliothek kann mit vorhandenen oder neuen Dokumenten arbeiten; sie stellt eine Menge von Funktionen bereit, die man mit den Dokumenten durchführen kann:

• Laden Sie Dokumente aus dem Dateisystem genauso wie von URLs oder Java-InputStreams
• Zerlegen und mischen Sie Dokumente, entfernen oder fügen Sie Seiten hinzu
• Zeichnen Sie neuen Inhalt auf eine neue Seite mit den standardmäßigen Befehlen zum Zeichnen von Java Graphics
• Schützen und verschlüsseln Sie Dokumente mit Kennworten. Setzen und ändern Sie Berechtigungen
• Exportieren Sie das Dokument als eine Folge von Bilder
• Drucken Sie Dokumente
• Setzen und lesen Sie Daten aus PDF-Formularfeldern
• Lesen und setzen Sie Lesezeichen in dem Dokument (Inhaltsverzeichnis)

Mit jPDFProcess kann Ihre Anwendung oder Server PDF-Dokumente anpassen und verarbeiten, um kundenspezifischen Inhalt an Ihre Kunden auszuliefern oder um automatisch PDF-Inhalte in Repositories zu verwalten.

Erste Schritte

Einstiegspunkt für den Einsatz von jPDFProcess ist com.qoppa.pdfProcess.PDFDocument. Diese Klasse wird gebraucht, um Dokumente in eine Anwendung zu laden, sie zu verändern und das Dokument zu speichern oder auszugeben. Die Klasse stellt drei Konstruktoren zur Verfügung, um PDF-Dateien aus dem Dateisystem, einer URL oder einem InputStream zu laden. Alle Konstruktoren haben als weiteren Parameter ein Objekt, das IPasswordHandler implementiert, dieses wird abgefragt, wenn die PDF-Datei zum Öffnen ein Kennwort verlangt. Für nicht verschlüsselte PDF-Dateien, kann der zweite Parameter “null” sein:

PDFDocument pdfDoc = new PDFDocument (new URL ("http://www.mysite.com/content.pdf"), null);

Diese Klasse stellt auch einen Konstruktor ohne Parameter zur Verfügung, um ein leeres Dokument anzulegen. Nachdem das Dokument geladen wurde, kann die Host-Anwendung Aufrufe vornehmen, um verfügbare Funktionen von jPDFProcess auszuführen.

Mischen und Zerlegen

PDFDocument definiert ein PDF-Dokument als eine Anzahl von Seitenobjekten. Einige der verfügbaren Funktionen der Bibliothek können Zugriffe auf Seitenebene vornehmen. Zum Beispiel, beim Mischen zweier Dokumente, könnte die Host-Anwendung die Seiten aus einem Dokument bestimmen und sie einem anderen Dokument hinzufügen.

PDFDocument pdfDoc1 = new PDFDocument ("doc1.pdf", null);
PDFDocument pdfDoc2 = new PDFDocument ("doc2.pdf", null);
for (int count = 0; count < pdfDoc1.getPageCount(); ++count)
{
pdfDoc2.appendPage (pdfDoc1.getPage (count));
}
pdfDoc2.saveDocument ("doc2.pdf");

Zerlegen arbeitet auf ähnliche Art und Weise:

PDFDocument pdfDoc1 = new PDFDocument ("doc1.pdf", null);
PDFDocument split1 = new PDFDocument();
PDFDocument split2 = new PDFDocument();
split1.appendPage (pdfDoc1.getPage(0));
split1.appendPage (pdfDoc1.getPage(1));
split2.appendPage (pdfDoc1.getPage(2));
split2.appendPage (pdfDoc1.getPage(3));
split1.saveDocument ("split1.pdf");
split2.saveDocument ("split2.pdf");

Auf einem Dokument zeichnen

jPDFProcess lässt die Host-Anwendung auf existierendem Inhalt genauso wie auf ganz neuen Seiten in einem Dokument zeichnen. Dieses Feature benutzt man, um vorhandene Dokumente mit Wasserzeichen zu versehen, PDF-Dokumente von Grund auf neu anzulegen u. ä. Um Inhalt zu zeichnen, stellt die Bibliothek ein Objekt zur Verfügung, das vom standardmäßigen Java Graphics2D-Objekt abgeleitet wurde und alle Methoden zum Zeichnen auf PDF gegenüber dem Bildschirm überschreibt. Das folgende Beispiel zeichnet einige Figuren auf einer vorhandenen Seite, legt dann eine neue Seite an und zeichnet auf ihr:

PDFDocument pdfDoc = new PDFDocument ("doc.pdf", null);
PDFPage existingPage = pdfDoc.getPage(0);
Graphics2D g2d = existingPage.createGraphics();
g2d.drawString ("This is a string", 72, 72);
g2d.drawImage (img, 100, 200, null);
 
PDFPage newPage = pdfDoc.appendNewPage (8.5 * 72, 11 * 72);
g2d = newPage.createGraphics();
g2d.drawRect (100, 100, 100, 100);
pdfDoc.saveDocument ("doc.pdf");

Verschlüsselung und Berechtigungen

jPDFProcess kann die Verschlüsselung hinzufügen oder verändern und Berechtigungen in einem Dokument setzen. Hierzu stellt die Bibliothek eine Methode zu Verfügung, setSecurity, diese übernimmt die neuen Kennworte und Berechtigungseinstellungen. Anzumerken ist, dass eine PDF-Datei zwei verschiedene Kennworte, ein Berechtigungs- oder Eigentümer- und ein Öffnen- oder Benutzer-Kennwort haben kann. Das Berechtigungskennwort wird nur beim Ändern der Berechtigungen einer PDF-Datei verlangt und nicht, um ein Dokument zu öffnen oder anzusehen. Das Öffnen-Kennwort wird verlangt, um ein Dokument zu öffnen.

// Load the document
PDFDocument pdfDoc = new PDFDocument ("input.pdf", null);
 
// Create permissions object to allow printing only
PDFPermissions perms = new PDFPermissions (false);
perms.setPrintAllowed(true);
 
// Set document security
pdfDoc.setSecurity("owner", "user", perms, null, PDFPermissions.ENCRYPTION_AES);
 
// Save the document
pdfDoc.saveDocument ("output.pdf");

Die Parameter der setSecurity-Methode sind:

• newPermissionsPwd – dies wird das neue Berechtigungskennwort.
• newOpenPwd – dies wird das neue Öffnen-Kennwort.
• permissions – PDFPermission-Objekt.
• currentPermissionsPwd – dies wird für den Fall benötigt, falls das PDF-Dokument bereits ein Berechtigungskennwort besitzt. Wie oben beschrieben, muss das Kennwort angegeben werden, um die Berechtigungen zu ändern und die Sicherheitseinstellungen in einem Dokument zu setzen.
• encryptType – PDFPermissions.ENCRYPTION_RC4, PDFPermissions.ENCRYPTION_AES, etc..

Sie können alle Sicherheitseinstellungen eines Dokuments durch Aufruf der PDFDocument.clearSecurity-Methode löschen. Dieser Methode übergibt man als Parameter das aktuelle Berechtigungskennwort, dieser Parameter kann auch auf “null” belassen werden, falls das Dokument kein Berechtigungskennwort besitzt.

In Bilder exportieren

jPDFProcess kann Bilder aus beliebigen Seiten eines PDF-Dokuments erzeugen. Mit dieser Funktionalität kann eine Anwendung das Dokument als eine Folge von Bildern exportieren. Bilder können wie folgt angelegt werden:

PDFDocument pdfDoc = new PDFDocument ("doc.pdf", null);
for (int count = 0; count < pdfDoc.getPageCount(); ++count)
{
BufferedImage bi = pdfDoc.getPage (count).getImage();
// Do something with the image
}

Ein Dokument drucken

Mit jPDFProcess können PDF-Dokumente mit oder ohne Druck-Dialog oder einer anderen Benutzer-Interaktion ausgedruckt werden. Das PDFDocument-Objekt stellt eine Reihe von Druck-Methoden zur Verfügung, um dies zu erreichen:

PDFDocument.print (PrintSettings printSettings);
PDFDocument.print (String printerName, PrintSettings printSettings);

Die erste Version der Methode zeigt einen Druck-Dialog an, um den Benutzer Drucker und Drucker-Eigenschaften auswählen zu lassen. Die zweite Version der Methode druckt das Dokument ohne Anzeige eines Druck-Dialogs auf einem benannten Drucker. Falls der Drucker-Name “null” ist, wird die Bibliothek auf dem Standard-Drucker ausdrucken.

Der zweite Parameter, PrintSettings, kontrolliert die Art und Weise wie jPDFProcess jede Seite druckt. Das Objekt hat verschiedene Eigenschaften, die von der aufrufenden Anwendung gesetzt werden können:

• AutoRotate – diese Einstellung teilt jPDFProcess mit, die Ausrichtung des PDF-Dokuments festzustellen und ungefähr auf einer Druckseite zu drucken. Falls das Dokument z. B. im Querformat ist, wird die Bibliothek es in diesem Format auf dem Drucker ausgeben. Wird dies auf “false” gesetzt, wird immer das Hochformat bei der Ausgabe auf dem Drucker verwendet.
• ShrinkToMargin – diese Einstellung teilt jPDFProcess 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.
• ExpandToMargin – Diese Einstellung teilt jPDFProcess 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 jPDFProcess 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 ExpandToPage-Option auf “false” gesetzt wurde.

Wenn ein PrintSettings-Objekt durch seinen Standard-Konstruktor angelegt wird, lauten die standardmäßigen Einstellungen:

• AutoRotate = true
• ShrinkToMargin = true
• ExpandToMargin = false
• CenterInPage = true

Also, by default document’s annotations are sent to the printer, but it is possible to hide them:

PrintSettings prSettings = new PrintSettings();
prSettings.setPrintAnnotations(false);
PDFDocument.print (prSettings);

You can find more information regarding printing PDF documents in the developer guide of our library jPDFPrint which API is packaged with jPDFProcess.

Printable / Pageable

Zusätzlich zu den Print-Methoden, implementiert PDFDocument für eine höhere Flexibilität die beiden Interfaces Printable und Pageable. Wird PDFDocument in diesem Sinne gebraucht, kann die aufrufende Anwendung ihren eigenen PrintJob erzeugen, die gewünschten Optionen setzen und dann PDFDocument 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 PDFDocument-Objekt implementiert Printable direkt, so dass es mit einem PrinterJob wie folgt verwendet werden kann:

PDFDocument pdfDoc = new PDFDocument ("doc.pdf", null);
PrinterJob pJob = PrinterJob.getPrinterJob();
pJob.setPrintable (pdfDoc);
 
HashPrintRequestAttributeSet printAttrSet = new HashPrintRequestAttributeSet (Chromaticity.COLOR);
pJob.print(printAttrSet);

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

PDFDocument pdfDoc = new PDFDocument ("doc.pdf", null);
PrinterJob pJob = PrinterJob.getPrinterJob();
pJob.setPageable (pdfDoc.getPageable (pJob));
 
HashPrintRequestAttributeSet printAttrSet = new HashPrintRequestAttributeSet (Chromaticity.COLOR);
pJob.print(printAttrSet);

You can find more information regarding printing PDF documents in the developer guide of our library jPDFPrint which API is packaged with jPDFProcess.

Mit Formularfeldern arbeiten

Felder in einer PDF-Datei sind in einer von Adobe so genannten AcroForm enthalten. jPDFProcess stellt einen Zugriff auf ein AcroForm-Objekt ausgehend von der PDFDocument-Klasse bereit; durch dieses Objekt kann die Host-Anwendung die in einem Dokument enthaltenen Felder lesen und ihre Daten lesen oder setzen.

Um eine Referenz auf die AcroForm zu erhalten, muss die Host-Anwendung PDFDocument.getAcroForm aufrufen. Diese Methode liefert einen Objekttyp com.qoppa.pdf.form.AcroForm zurück.
pdfDoc.getAcroForm();

Die Host-Anwendung kann dann dieses Objekt benutzen, um eine Liste der Felder des Dokuments zu erhalten und um einzelne Felder über den Namen zu lesen. Die Feld-Objekte ihrerseits haben Methoden, um ihren aktuellen Wert zu lesen oder zu setzen.

// Get the list of fields in the document
Vector fieldList = pdfDoc.getAcroform().getFieldList();

Nachdem die Anwendung die Feldwerte gesetzt oder gelesen hat, kann sie die PDFDocument saveDocument-Methode aufrufen, um das aktualisierte Dokument zu speichern.

// Get a field by name and set its value
TextField companyField = (TextField) pdfDoc.getAcroForm().getField( "CompanyName");
companyField.setValue("Qoppa Software");
 
// Save the document
pdfDoc.saveDocument ("output.pdf");

Sie können Formularfelder in einer PDF-Datei durch Aufruf der PDFDocument.flattenFields-Methode verflachen. Diese Methode malt den Inhalt der Felder direkt auf die Seiten und entfernt die Felder aus dem Dokument. flattenFields hat einen boolschen Parameter, der anzeigt, ob Schaltflächen zu malen sind oder nicht. Gewöhnlich will man, dass dieser Flag auf “false” eingestellt ist.

You can find more information regarding working with PDF forms in the developer guide of our library jPDFFields which API is packaged with jPDFProcess.

Innerhalb J2EE arbeiten

jPDFProcess kann innerhalb eines Servlets in einem J2EE-Server benutzt werden, um Dokumente aus einem Repository zu laden, Dokumente entsprechend dem Zustand einer Benutzer-Verbindung kundenspezifisch anzupassen und die geänderten Dokumente direkt in einem Browser anzuzeigen. Der erste Schritt ist eine Servlet-Klasse anzulegen, die auf GET- und / oder POST-Requests antwortet. Innerhalb einer dieser beiden Requests würde der Code ungefähr so aussehen:

// Get servlet output stream
ServletOutputStream sOut = res.getOutputStream();
res.setContentType( "application/pdf" );
res.setHeader("Content-disposition", "attachment; filename=" + "report.pdf" );
 
// Load a PDF from the server file system. This PDF can come from a database or any other source
PDFDocument pdfDoc = new PDFDocument ("/pdfdocs/somedoc.pdf", null);
 
// Customize the document
Graphics2D g2d = pdfDoc.getPage (0).createGraphics();
g2d.drawString ("Custom Message", 72, 72);
 
// Save the document to the servlet output stream. When writing to this stream,
// the output goes directly to the client browser
objDocument.saveDocument(sOut);
 
// Close the server output stream
sOut.close();

Wenn diese Methode benutzt wird, sind keine temporären Dateien auf dem Server oder dem Client erforderlich, dies erhöht die Sicherheit und Performance wenn PDF-Inhalt ausgeliefert wird.

Verteilung und JAR-Dateien

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

Um JPEG 2000-Bilder zu unterstützen, verwendet jPDFProcess die Java Advanced Imaging (JAI)-Klassen. Da dieses API nur für Java 1.4.2 verfügbar ist, benötigt jPDFProcess 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.

Um TIFF-Bilder mittels PDFPage.savePageAsTIFF zu exportieren, verlangt jPDFProcess die Java Advance Imaging codec Klassen. Diese Klassen befinden sich in jai_codec.jar, das auch in der Installation des Evaluation-Programms enthalten ist.

Javadoc API
Source Code Samples