TUTORIALS

 Basics: jPDF + Web applications

As easy as 1, 2, 3...

Introduction

In this tutorial we will discuss how Crionics jPDF can be used in a web-based environment. We will explore the differences from a regular application as far as web technologies are concerned, and we will provide solutions that will circumvent typical pitfalls. Finally, we will provide some sample source code and pointers to help you resolve upcoming issues.

The main difference between regular and web applications are the following:

• Web apps deal with streams of data rather than files. Each stream response must be given a type (mime type) and a length.
• Because multiple people can hit a servlet at the same time, a web application is typically multi-threaded, and special care must be taken regarding concurrency.
• As clients (browsers) typically cache data, a work-around solution can be implemented when required.
• Last but not least, web apps usually run on a server in a restricted environment in which restrictions may apply: memory restrictions; work load restrictions; file access restrictions; etc.; ...

Working with streams and caching

NOTE: It is assumed that the reader has sound knowledge of servlets and web technologies in general.

Let's get back to the PdfDocument object and quickly review how to use it.

A typical servlet will instantiate one or several PdfDocuments, will perform some actions and will send documents back to the browser.
In the example below we open a template document, update one of its form fields and send it back to the client.

public class MyServlet extends HttpServlet
{

public long getLastModified(HttpServletRequest request)
{

// Handle cache refresh issues:
return System.currentTimeMillis();

}

public void doGet(HttpServletRequest req, HttpServletResponse res) throws IOException, ServletException
{

doPost(req, res);

}

public void doPost(HttpServletRequest req, HttpServletResponse res) throws IOException, ServletException
{

PdfDocument doc = null;

// Process the web request:
try
{

// Open the document - note that the document is instantiated in the
// method to resolve any concurrency issues:
doc = new PdfDocument("subscription.pdf");

// Apply changes:
TemplateModule tm = doc.getTemplateModule();
((TextField)tm.getField("name_field")).setValue(req.getParameter("name_param"));

// Send the document to the client browser:
saveServlet(res, doc);

}
catch (Exception e)
{

throw new ServletException(e.toString());

}
finally
{

// Close the document and free all the memory resources associated with it:
if (doc != null)
{

doc.close();

}

}

}

}

The call saveServlet() uses of the method saveCopy() to fill the output stream with the updated PDF Document.

saveCopy(OutputStream)

Incrementally saves a copy of the document to the specified destination. As opposed to the other methods, the current document is not changed to the destination after this call. Typically used in Servlet environments.

The method sets the stream mime type and its length and outputs the modified document.

public void saveServlet(HttpServletResponse res, PdfDocument doc) throws IOException, PdfException
{

// Set the mime Type:
res.setContentType("application/pdf");

// Set the stream length:
res.setContentLength(doc.getDescription().getSize());

// Stream the document back to the user browser:
doc.saveCopy(res.getOutputStream());

// Make sure the OutputStream buffer is flushed:
res.flushBuffer();

}