TUTORIALS

 Basics: Opening, saving and closing a document

As easy as 1, 2, 3...

Opening a document

The jPDF API maps the memory representation of a PDF Document using the PDFDocument class. The screen shot below shows a subset of its methods. For more specific information on modules, actions, preferences and credentials, refer to respective tutorials on each.

By using the default constructor PdfDocument(), the document is created in memory. However, if you need to build a document from an existing file, you will have to use one of the following constructors:

PdfDocument(File file)	Creates an instance from a file.
PdfDocument(String file)	Creates an instance from a string path.
PdfDocument(byte[] document)	Creates an instance from a document in memory. Should be avoided.
PdfDocument(ByteReader reader)	Used when you need to build your own PDF accessor, such as one that reads documents from sockets or streams.

jPDF uses an intelligent caching technique to minimize IO and to optimize resource allocation: only the required elements are read from the file system, which ensures that you won't get an OutOfMemory error. The jPDF Parser also contains a smart engine that will correct malformed documents - typically documents transferred as ASCII or those generated from a non-standard API.

The following code will open a document from a file called "myDocument.pdf":

PdfDocument document=new PdfDocument("myDocument.pdf");

Once a document is opened, you can use methods such as getDescription() to gather information about the author, or use getSecurity() to get information about its built-in security features. You can also access modules that are more fully described in another tutorial.

Saving a document

No matter how the document was instantiated (either from an existing file or as a new document in memory), you will have an instance of a PdfDocument that will need to be saved at some point in time.

To check if the document contains any updates, you can use the isUpdated() method which returns TRUE if the document needs to be saved.

jPDF Provides different saving policies, depending on the save method used:

save()	Incrementally updates the document. Extremely fast as it only appends the documents with the changed elements.
saveAs()	Incrementally saves the document to a new destination. The current instance of the document will be changed so that any changes in the document made after this call will be saved to the specified destination.
saveAsNew()	Saves the document as a new document with the elements in their latest form as opposed to the incremental updates from the above methods. This typically results in smaller documents at the expense of a higher save delay. All the changes in the document made after this call will be saved to the specified destination.
saveCopy()	Incrementally saves a copy of the document to the specified destination. As opposed to the other methods, the current instance of the PdfDocument object is not changed to the destination after this call.

Closing a document

To close a document, call close() in the document instance.

document.close();

When a document is closed, all resources associated with it are released to the garbage collector. It is also possible to clear the cache without calling close() by using the purgeCache() method. Because jPDF is usually quite smart in optimizing resource, this latter method should be avoided.