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
Distribution and JAR Files

Javadoc API
Source Code Samples
End-User Guide

Introduction

jPDFNotes is a Java bean that can be embedded in Java applications to deliver PDF content to your users and allow them to add notes and comments and then save the annotated document. jPDFNotes is built on Qoppa’s proprietary PDF technology and so does not need the installation of any third party software or drivers. jPDFNotes integrates seamlessly into your application and delivers the most features, performance and reliability of any Java PDF viewer.

By using jPDFNotes in your application, you can implement custom document revision cycles with complete control and security over your PDF content. jPDFNotes 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

jPDFNotes provides a standard Java bean that can be added to any GUI container, the bean class is com.qoppa.pdfNotes.PDFNotesBean. 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. jPDFNotes 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 jPDFNotes. Once a PDFNotesBean 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

PDFNotesBean notesBean = getNotesBean ();
notesBean.loadPDF ("c:\\test.pdf");

Customizing the Toolbar

The toolbars in jPDFNotes 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 PDFNotesBean 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 notesBean is a reference to a PDFNotesBean:

To hide the annotations toolbar:

notesBean.getAnnotToolbar().setVisible (false);

To hide the open button:

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

To disable the print button:

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

Working with Form Fields

jPDFNotes allows users to visually fill interactive form fields. Read more information in jPDFNotes’ end-user guide.

jPDFNotes also makes it possible to work with form fields programmatically in order to add more functionality. Fields in a PDF file are contained in what Adobe calls an AcroForm. jPDFNotes provides access to an AcroForm object from the PDFNotesBean class and through this object, the host application can get the fields present in the document and get or set their data.

To get a reference to the AcroForm, the host application needs to call PDFNotesBean.getAcroForm. 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.

To import, export fields from/to FDF, XFDF, XDP or XML files:

notesBean.getDocument().getAcroForm().exportAsFDF("C:\\mydoc.xfdf", true);
notesBean.getDocument().getAcroForm().importFDF("C:\\mydoc.xfdf");

Working with Annotations

jPDFNotes comes with a toolbar that allows users to visually add all type of PDF annotations (graphical annotations, text annotations, text markups, etc…). Read more information in jPDFNotes’ end-user guide.

jPDFNotes also makes it possible to work with annotations programmatically in order to add more functionality. jPDFNotes 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, first access the PDF document, then the page:

Vector annots = notesBean.getDocument().getIPage(0).getAnnotations();

The method getAnnotations() returns a vector of annotation objects. 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, get the AnnotationFactory to create a new annotation, then call the method PDFNotesBean.addAnnotation:

IAnnotationFactory annotFactory = pdfNotes.getMutableDocument().getAnnotationFactory();
Circle newCircle =  annotFactory.createCircle("Circle Note");
newCircle.setColor(Color.red);
newCircle.setRectangle(new Rectangle2D.Double(100, 100, 40, 40));
notesBean.addAnnotation(newCircle, 0);

To import and export annotations from/to fdf or xfdf files:

notesBean.getMutableDocument().exportAnnotsAsXFDF("C:\\mydoc.xfdf");
notesBean.getMutableDocument().importAnnotsFromXFDF("C:\\mydoc.xfdf");

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

Digitally Signing the Document

jPDFNotes has a default implementation for signing and verifying digital signatures visually. Read more information in jPDFNotes’ end-user guide.

jPDFNotes also allows to create and sign digital signature fields programmatically in order to add or customize the signing process. There are 3 steps to add a new digital signature to a PDF document with jPDFNotes: 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

jPDFNotes 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, jPDFNotes 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 PDFNotesBean. To do this, the host application needs to call the setPDFSaver method in the PDFNotesBean with an object that implements IPDFSaver. IPDFSaver is an interface that is called anytime that the PDFNotesBean needs to save a document. The interface consists of a single method with three parameters, the reference to the PDFNotesBean 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 PDFNotesBean 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

jPDFNotesBean 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 PDFNotesBean.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().

Distribution and JAR Files

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

Javadoc API
Source Code Samples
End-User Guide