jPDFEditor Developer Guide

Contents

Introduction
Getting Started
Opening a Document
Customizing the Toolbar
Working with Form Fields
Working with Annotations
Signing the Document
Saving the Document
Additional Functions
Integration with jPDFProcess

Distribution and JAR Files
Javadoc API
Source Code Samples
End-User Guide

Introduction

jPDFEditor is a Java bean that can be embedded in Java applications to deliver PDF content to your users and allow them to edit PDF documents and then save the annotated document. jPDFEditor is built on Qoppa’s proprietary PDF technology and so does not need the installation of any third party software or drivers. jPDFEditor integrates seamlessly into your application and delivers the most features, performance and reliability of any Java PDF viewer. By using jPDFEditor in your application, you can implement custom document revision cycles with complete control and security over your PDF content. jPDFEditor lets you customize the functions available to your users, such as opening, saving and printing documents, so that you control the flow of content.

Getting Started

jPDFEditor provides a standard Java bean that can be added to any GUI container, the bean class is com.qoppa.pdfEditor.PDFEditorBean. The bean can be added to a container either programmatically or using any standard GUI editor in your development environment. Once the bean has been added, your application can start showing PDF documents and your users can start adding notes and comments to them. jPDFEditor can load PDF documents both programmatically based on the application logic, or by letting users open their own PDF documents by clicking on the open button in the toolbar. The host application can also customize the toolbar by calling the getToolbar() method and removing or adding buttons, override the button handlers, or even hiding the entire toolbar. Action handlers on the toolbar buttons can be overridden to provide custom code to handle the functions. For example, your application can override the open function to show the user a limited list of PDF documents that can be opened.

Opening a Document

Loading and displaying a document programmatically is very simple using jPDFEditor. Once a PDFEditorBean bean has been added to a container, the host application simply needs to call one of the loadPDF methods and the library will load and display the first page of the document. The three versions of the loadPDF method take a file name, a URL or an InputStream as parameters

PDFEditorBean bean = getViewerBean ();
bean.loadPDF ("c:\\test.pdf");

Customizing the Toolbar

The toolbars in jPDFEditor can be shown or hidden according to the needs of host application. Additionally, all the buttons in the toolbar are accessible, so they can be enabled/disabled or hidden. The PDFEditorBean class provides two methods, getAnnotToolbar and getEditToolbar that return references to the annotations toolbar and the navigation toolbar respectively. Each of these toolbars provide methods to access the buttons within them so that the host application can disable or hide the buttons individually. Please refer to the API for more detail. The following examples assume that bean is a reference to a PDFEditorBean: To hide the annotations toolbar:

bean.getAnnotToolbar().setVisible (false);

To hide the open button:

bean.getEditToolbar().getjbOpen ().setVisible (false);

To disable the print button:

bean.getToolbar().getjbPrint().setEnabled (false);

Working with Form Fields

Fields in a PDF file are contained in what Adobe calls an AcroForm. jPDFEditor provides access to an AcroForm object from the PDFEditorBean class and through this object, the host application can get the fields present in the document and get or set their data.

// getting the acroform from the bean
Acroform acroform = bean.getAcroForm();
// loading an fdf file that contains fields data 
acroform.importFDF("fielddata.fdf");
// or getting the list of all fields
Vector fields = acroform.getFieldList(); 
// or getting a field by name 
acroform.getField("LastName");
// work with field(s)

The method returns an object of type com.qoppa.pdf.AcroForm. The host application can then use this object to get the list of fields in the PDF document and to get individual fields by name. The field objects in turn have methods to get or set their current value.

Working with Annotations

jPDFEditor provides access to all annotations contained in a PDF document and allows to get and their properties. New annotations can also be created and added to the document. Host applications have the flexibility to customize default annotations properties such as color and to save and retrieve the properties in XML format (in order to save user preferences for instance).

To access the annotations, one has to first access the PDF document by calling PDFEditorBean.getDocument() which returns an object that implements com.qoppa.pdf.dom.IPDFDocument. From the document, individual pages can be accessed by calling IPDDocument.getPage() which returns an object implementing com.qoppa.pdf.dom.IPDFPage. The list of annotations contained in a page can then be retrieved by calling IPDFPage.getAnnotations(). This method returns a vector of annotation objects.

// get the document
IPDFDocument doc = bean.getDocument();
// get first page
IPDFPage page = doc.getPage(0);
// get annotations
Vector annotations = page.getAnnotations();
for(int count = 0; count< annotations.size(); count++)
{
Annotation annot = (Annotation) annotations.get(count);
// work with annotations
}

The annotation objects in turn have methods to get or set their current properties. Look at the package com.qoppa.pdf.annotations for all different types of annotations supported.

To create new annotations, call the appropriate method in the AnnotationFactory class in the com.qoppa.pdf.annotations package, then call the method PDFEditorBean.addAnnotation.

To customize default annotations settings and editing properties such as color or font, look at the classes contained in the com.qoppa.pdfEditor.settings. Settings can be saved and retrieved through the AnnotationsTools.toXMLString and setFromXML methods.

Digitally Signing the Document

jPDFEditor allows to create and sign digital signature fields in a PDF document. There are 3 steps to add a new digital signature to a PDF document with jPDFEditor: create a new digital signature field, load digital id from a keystore to create a SignatureInformation object , and apply the signature.

// Create a signature field on the first page
Rectangle2D signBounds = new Rectangle2D.Double (36, 36, 144, 48);
SignatureField signField = bean.addSignatureField("signature", signBounds, 0);
 
// Load the keystore that contains the digital id to use in signing
FileInputStream pkcs12Stream = new FileInputStream ("https://www.qoppa.com/files/pdfnotes/guide/sourcesamples/keystore.pfx");
KeyStore store = KeyStore.getInstance("PKCS12");
store.load(pkcs12Stream, "store_pwd".toCharArray());
pkcs12Stream.close();
 
// Create signing information
SigningInformation signInfo = new SigningInformation (store, "key_alias", "key_pwd");
 
// Apply digital signature
bean.signDocument(signField, signInfo, new File("Doc_signed.pdf"));

Saving the Document

jPDFEditor provides a save button on the navigation toolbar, this button has the following default behaviour:

• If the PDF document was opened from the file system, jPDFEditor will save the modified document to the same location.
• If the PDF document was opened from a URL or from and InputStream, the library will prompt the user for a file name and save it to that location.

This default behaviour can be overridden by the host application by registering a PDF Saver with the PDFEditorBean. To do this, the host application needs to call the setPDFSaver method in the PDFEditorBean with an object that implements IPDFSaver. IPDFSaver is an interface that is called anytime that the PDFEditorBean needs to save a document. The interface consists of a single method with three parameters, the reference to the PDFEditorBean object, the name of the PDF document and if the document was opened from a file, a reference to a File object pointing to the file that the document was opened from. The host application can use this to save the modified documents to locations other than the file system and with or without user intervention. For instance, the application might need to save the document to a database server or to an application server. Within the method, the host application can get a reference to the document by calling the getDocument method in the PDFEditorsBean object. It can then use the PDFDocument object returned to write the PDF content to a file or to an OutputStream. By using a ByteArrayOutputStream, the application can get a byte array holding the contents of the PDF document.

Additional Functions

jPDFEditorBean provides a number of additional functions to work with and manipulate PDF documents. The library provides these functions by giving access to an interface class that represents the underlying PDF document. The PDFEditorBean.getDocument method returns an object that implements com.qoppa.pdf.dom.IPDFDocument. Some of the information and functions this object provides are:

• Get information about the PDF document such as the author, creation date and more – IPDFDocument.getDocumentInfo().
• Print the PDF document programmatically by calling – IPDFDocument.print().
• Get the bookmark tree (the table of contents) – IPDFDocument.getRootBookmark().
• Get information about each page – IPDFDocument.getIPage(). This method returns an object that implements IPDFPage.
• Get each page’s size, crop box, trim box and bleed box – IPDFPage.getMediaBox(), IPDFPage.getCropBox(), IPDFPage.getTrimBox(), IPDFPage.getBleedBox().
• Export each page to an image – IPDFPage.getImage().

Integration with jPDFProcess

If you need to access additional functions in jPDFProcess, the PDF document can be passed from jPDFProcess to jPDFEditor using the following code:

// load a PDF document in jPDFProcess
PDFDocument pdfDoc = new PDFDocument("C:\mydoc.pdf", null);
 
// here you can work with the PDF document 
// using jPDFProcess
 
// load the document into the jPDFEditorBean
pdfEditorBean.setDocument(pdfDoc);

Distribution and JAR Files

Required and optional jar files for jPDFEditor can be found on the jPDFEditor Download page.

Javadoc API
Source Code Samples
End-User Guide