[Dataisland-developer] Creating PDFs in a Web Application

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <meta http-equiv="Content-Type" content="text/html;charset=ISO-8859-1">
  <title></title>
</head>
<body>
Yet again, from the Oreilly Network, on creating PDFs dynamically.<br>
<br>
v-o<br>
<br>
<br>
<a href="http://www.oreillynet.com/"><img
 src="cid:par...@up..." width="110" height="80"
 align="left" alt="O'Reilly Network" border="0"></a> <dummy>&nbsp;&nbsp;&nbsp;</dummy>
<table border="0" cellspacing="0" width="468">
  <tbody>
    <tr>
      <td><!-- dy --> 				<iframe
 src="http://ad.doubleclick.net/adi/onjava.ds/wsjart;pos=top_wsjart;sz=468x60;ord=1486759588?"
 width="468" height="60" frameborder="0" marginwidth="0"
 marginheight="0" scrolling="no">
				&amp;lt;script&amp;gt;&amp;lt;/script&amp;gt; 				</iframe> 				
      <noscript> 				<a
href="http://ad.doubleclick.net/jump/onjava.ds/wsjart;abr=!ie;pos=top_wsjart;sz=468x60;ord=1486759588?"><img
src="http://ad.doubleclick.net/ad/onjava.ds/wsjart;abr=!ie;kw=pos=top_wsjart;sz=468x60;ord=1486759588?"
border="0" width="468" height="60" alt="Advertisement" /></a> 				</noscript>
      </td>
    </tr>
  </tbody>
</table>
<br clear="all">
&nbsp;<font face="verdana,arial,helvetica" size="1">Published on <b><a
 href="http://www.oreillynet.com/">The O'Reilly Network</a></b> (<a
 href="http://www.oreillynet.com/">http://www.oreillynet.com/</a>)<br>
&nbsp;<a
 href="http://www.onjava.com/pub/a/onjava/2003/06/18/dynamic_files.html">http://www.oreillynet.com/pub/a/onjava/2003/06/18/dynamic_files.html</a><br>
&nbsp;<a href="http://www.onjava.com/pub/a/general/print_code.html">See this</a>
if you're having trouble printing code examples</font><br clear="all">
<!-- CS_PAGE_BREAK -->
<h2> Dynamically Creating PDFs in a Web Application</h2>
by <a href="http://www.onjava.com/pub/au/1230">Sean C. Sullivan</a><br>
<!--  sidebar begins  --><!--  don't move sidebars  --><!--  sidebar ends  -->
06/18/2003
<p>On a recent logistics project, a customer asked our team to build a
web site that would allow users to query a legacy system for shipment
information.  The customer defined three main requirements:</p>
<ol>
  <li>The shipping information had to be returned in the form of a PDF
document.</li>
  <li>The PDF file must be downloadable through a web browser.</li>
  <li>The PDF file must be viewable using the Adobe Acrobat Reader.</li>
</ol>
<p>Our team had plenty of experience with J2EE web applications, but we
had little experience with PDF documents. We needed to find a pure Java
class library that could produce sophisticated PDF documents in a
server-side web application. We found a solution that completely met
our needs: <a href="http://www.lowagie.com/iText/">iText</a>.</p>
<h3>iText Class Library</h3>
<p>iText is an open source pure Java class library for creating and
manipulating PDF documents. Bruno Low</p>
<p>agie and Paulo Soares lead the project. The iText API enables a Java
developer to programmatically create PDF documents. iText delivers a
rich set of feature</p>
<!--  sidebar ends  -->
<ul>
  <li>Support for both PDF and FDF documents</li>
  <li>Various page sizes</li>
  <li>Landscape or portrait layouts</li>
  <li>Margins</li>
  <li>Tables</li>
  <li>Hyphenation</li>
  <li>Page headers</li>
  <li>Page footers</li>
  <li>Page numbering</li>
  <li>Barcodes</li>
</ul>
<ul>
  <li>Fonts</li>
  <li>Colors</li>
  <li>Document encryption</li>
  <li>JPEG, GIF, PNG, and WMF images</li>
  <li>Ordered and unordered lists</li>
  <li>Shading</li>
  <li>Watermarks</li>
  <li>Document templates</li>
</ul>
<p>iText is an open source library. At the time of this writing, the
iText software is available under a dual license: the Mozilla Public
License (MPL) and the LGPL. Consult the iText web site for details.  In
this article, you'll see the iText API in action.  We will demonstrate
how to use iText and servlets to dynamically generate PDF documents in
a server-side application.</p>
<h3>Getting Started</h3>
<p>First, you will need to obtain the iText JAR file.  Visit the iText
web site and download the current release. At the time of this writing,
the current iText release is version 0.99.  The iText web site provides
API documentation and a comprehensive tutorial.</p>
<p>In addition to iText, we'll be using servlets, too.  If you aren't
familiar with servlets, you can learn about them in Jason Hunter's
book, <a
 href="http://www.oreilly.com/catalog/jservlet2/index.html?CMP=IL7015">Java
Servlet Programming</a>. You will need to obtain a J2EE application
server or a standalone servlet engine. Some good open source options
are <a href="http://jakarta.apache.org/tomcat/">Tomcat</a>, <a
 href="http://jetty.mortbay.com/jetty/index.html">Jetty</a>, and <a
 href="http://www.jboss.org/">JBoss</a>.  The rest of this article
assumes that you are using Jakarta Tomcat 4.1.</p>
<h3>The iText API</h3>
<p>The iText API is intuitive and easy to use. Using iText, you will be
able to programmatically create customized PDF documents. The iText
library consists of the following packages:</p>
<pre><code>com.lowagie.servlets
com.lowagie.text
com.lowagie.text.html
com.lowagie.text.markup
com.lowagie.text.pdf
com.lowagie.text.pdf.codec
com.lowagie.text.pdf.hyphenation
com.lowagie.text.pdf.wmf
com.lowagie.text.rtf
com.lowagie.text.xml
com.lowagie.tools</code></pre>
<p>For generating PDF files, you'll need only <code>com.lowagie.text</code>
and <code>com.lowagie.text.pdf</code>.</p>
<p>Our example application uses these iText classes:</p>
<pre><code>com.lowagie.text.pdf.PdfWriter
com.lowagie.text.Document
com.lowagie.text.HeaderFooter
com.lowagie.text.Paragraph
com.lowagie.text.Phrase
com.lowagie.text.Table
com.lowagie.text.Cell</code></pre>
<p>The key classes are <code>Document</code> and <code>PdfWriter</code>.
You will always use both of these classes when creating PDF documents. <code>Document</code>
is an object-oriented representation of a PDF document. You can add
content to the document by invoking methods provided by the <code>Document</code>
class. A <code>PdfWriter</code> object associates a <code>Document</code>
with a <code>java.io.OutputStream</code> object.</p>
<!--  sidebar begins  -->
<table width="45%" border="0" cellspacing="12" cellpadding="6"
 align="right">
  <tbody>
    <tr>
      <td valign="top" bgcolor="#efefef">
      <h4>Coordinate System for iText Documents</h4>
      <p>When I wrote my first iText program, I stumbled over the
coordinate system. I naively assumed that iText's coordinate system was
identical to Swing's coordinate system. This is not the case.</p>
      <p>In Swing, the origin (0, 0) is located in the upper left-hand
corner of a component.  In iText, the origin is located in the bottom
left-hand corner of a page.</p>
      </td>
    </tr>
  </tbody>
</table>
<!--  sidebar ends  -->
<h3>Using iText in a Web Application</h3>
<p>During your design phase, you must decide how you plan to use iText.
I've built web applications using both of the following techniques.</p>
<h4>Technique A</h4>
<p>Create the PDF file on the server's filesystem. The application
uses <code>java.io.FileOutputStream</code> to write the file to the
server's filesystem. The user will download the file via HTTP <code>GET</code>.</p>
<h4>Technique B</h4>
<p>Create the PDF file in memory using <code>java.io.ByteArrayOutputStream</code>.
The application sends the PDF bytes to the client via the servlet's
output stream.</p>
<!--  sidebar begins  -->
<table width="220" border="0" cellspacing="12" cellpadding="6"
 align="right">
  <tbody>
    <tr>
      <td valign="top" bgcolor="#efefef">
      <p class="secondary"><b>Source Code</b></p>
      <p class="secondary">Download the source code for this example:<br>
      <a
 href="http://www.onjava.com/onjava/2003/06/18/examples/pdfservlet-files.zip">pdfservlet-files.zip</a></p>
      </td>
    </tr>
  </tbody>
</table>
<!--  sidebar ends  -->
<p>I prefer technique B to technique A because the application does not
write to the server's filesystem, and the application is guaranteed to
work in a clustered server environment.  Technique A can fail if your
application runs in a clustered environment, and the server cluster
does not provide session affinity.</p>
<h3>Example: PDFServlet</h3>
<p>Our <a
 href="http://www.onjava.com/onjava/2003/06/18/examples/created-by-PDFServlet.pdf">example
application</a> consists of a single class: <code>PDFServlet</code>.
This servlet uses technique B from the previous section. The <code>OutputStream</code>
is a <code>java.io.ByteArrayOutputStream</code>. With <code>ByteArrayOutputStream</code>,
the PDF document bytes will be in memory. When <code>PDFServlet</code>
receives an HTTP request, it will dynamically generate a PDF document
and send the document to the client.</p>
<p>The <code>PDFServlet</code> class extends <code>javax.servlet.http.HttpServlet</code>
and imports two of the iText packages, <code>com.lowagie.text</code> and <code>com.lowagie.text.pdf</code>.</p>
<h4>The <code>doGet</code> Method</h4>
<p>Most servlets override either the <code>doPost</code> method or the <code>doGet</code>
method. Our servlet is no different. The <code>PDFServlet</code> class
overrides the <code>doGet</code> method. The servlet will generate a
PDF file any time it receives an incoming HTTP <code>GET</code> request.</p>
<p>In a nutshell, the servlet's <code>doGet</code> method does the
following:</p>
<ol>
  <li>Creates a <code>ByteArrayOutputStream</code> object that contains
the PDF document bytes.</li>
  <li>Sets the HTTP response headers on the response object.</li>
  <li>Gets the servlet output stream.</li>
  <li>Writes the document bytes to the servlet output stream.</li>
  <li>Flushes the servlet output stream.</li>
</ol>
<p><img src="cid:par...@up..."><br>
<em>Figure 1. Editing <code>doGet</code> in Eclipse</em></p>
<h4>The <code>generatePDFDocumentBytes</code> Method</h4>
<p>The <code>generatePDFDocumentBytes</code> method is responsible for
creating the PDF document. The three most important objects in this
method are the <code>Document</code> object, the <code>ByteArrayOutputStream</code>
object, and the <code>PdfWriter</code> object. The <code>PdfWriter</code>
associates the <code>Document</code> with the <code>ByteArrayOutputStream</code>.</p>
<pre><code>Document doc = new Document();
ByteArrayOutputStream baosPDF = new ByteArrayOutputStream();
PdfWriter docWriter = null;
docWriter = PdfWriter.getInstance(doc, baosPDF);
// ...
</code>
</pre>
<p>Adding content to a <code>Document</code> is done with the <code>add</code>
method.</p>
<pre><code>doc.add(new Paragraph(
    "This document was created by a class named: "
    + this.getClass().getName()));

doc.add(new Paragraph(
    "This document was created on "
    + new java.util.Date()));
</code>
</pre>
<p>When you are done adding content, close the <code>Document</code>
and <code>PdfWriter</code> objects.</p>
<pre><code>doc.close();
docWriter.close();
</code>
</pre>
<p>After closing the document, the <code>ByteArrayOutputStream</code>
object is returned to the caller.</p>
<pre><code>return baosPDF;
</code>
</pre>
<p> The <code>ByteArrayOutputStream</code> contains all bytes for the
PDF document.</p>
<h4>HTTP Response Headers</h4>
<p>In this application, we care only about four HTTP response headers: <code>Content-type</code>,<code>Content-disposition</code>,<code>Content-length</code>,
and <code>Cache-control</code>.  If you've never worked with HTTP
headers before, consult the HTTP 1.1 specification.</p>
<p>Examine the <code>doGet</code> method in the <code>PDFServlet</code>.
You'll notice that the HTTP response headers are set before any data is
written to the servlet output stream. This is an important, yet subtle,
point.</p>
<p>Let's look at each response header in more detail.</p>
<table width="100%" border="0" cellspacing="0" cellpadding="0">
  <tbody>
    <tr>
      <td>
      <p class="secondary"><!-- CS_PAGE_INDEX --> </p>
      <br>
      </td>
      <td>
      <p class="secondary" align="right"> <a
 href="http://www.onjava.com/lpt/a/%3C%21--CS_NEXT_REF--%3E"> </a></p>
      <br>
      </td>
    </tr>
  </tbody>
</table>
<!-- CS_PAGE_BREAK -->
<p><!-- CS_PAGE_INDEX --> </p>
<h4><code>Content-type</code></h4>
<p>In servlets, <code>HttpServletResponse</code> has a content type
that indicates the type of content that the response contains. For PDF
files, the content type is <code>application/pdf</code>.  If the
servlet does not set a content type, the web browser may have a
difficult time determining how to handle the file.</p>
<p><code>PDFServlet</code> sets the content type with the following
line: </p>
<pre><code>resp.setContentType("application/pdf");</code></pre>
<h4><code>Content-disposition</code></h4>
<p>The <code>Content-disposition</code> header provides information
that helps a web browser identify the content of the HTTP response. 
When a web browser reads this header, it can determine:</p>
<ul>
  <li>That the HTTP response contains a file.</li>
  <li>The name of the file contained in the response.</li>
  <li>Whether the file should be displayed inside of the browser's main
window or viewed by an external application.</li>
</ul>
<p>RFC 2183 provides a full explanation of the <code>Content-disposition</code>
header.</p>
<p>By setting the <code>Content-disposition</code> header
appropriately, the servlet can instruct the browser to display the file
"inline," or to treat it like an attachment.</p>
<p><em>Example 1. Displaying a file inline</em></p>
<pre><code>Content-disposition: inline; filename=foobar.pdf</code></pre>
<p><em>Example 2. Attaching a file to the response</em></p>
<pre><code>Content-disposition: attachment; filename=foobar.pdf</code></pre>
<p>The following pseudo-code demonstrates how to set the header:</p>
<pre><code>public void doGet(HttpServletRequest req, HttpServletResponse resp)
{
	// ... 
	resp.setHeader(
		"Content-disposition",
		"inline; filename=foobar.pdf" );
	// ... 
}</code></pre>
<h4><code>Cache-Control</code> Headers</h4>
<p>Depending upon the nature of your application, you may or may not
want web browsers to cache the PDF files that you are generating. 
There are a variety of HTTP headers that a server-side web application
can use to control caching of content.  Some examples are:</p>
<ul>
  <li> <code>Cache-Control: no-cache</code> </li>
  <li> <code>Cache-Control: no-store</code> </li>
  <li> <code>Cache-Control: must-revalidate</code> </li>
  <li> <code>Cache-Control: max-age=30</code> </li>
  <li> <code>Pragma: no-cache</code> </li>
  <li> <code>Expires: 0</code> </li>
</ul>
<p>A full explanation of <code>Cache-Control</code> headers is found in
the HTTP 1.1 specification.</p>
<p>The <code>PDFServlet</code> sets <code>Cache-Control</code> to <code>max-age=30</code>.
This header tells the web browser to cache the file for a maximum of 30
seconds.</p>
<h4><code>Content-length</code></h4>
<p>The <code>Content-length</code> header must be set to the number of
bytes in the PDF file.  If the <code>Content-length</code> header is
not set correctly, the web browser may not be able to display the file.
Example code might be:</p>
<pre><code>ByteArrayOutputStream baos = getByteArrayOutputStream();
resp.setContentLength(baos.size());</code></pre>
<h4>Sending the PDF Document to a Web Browser</h4>
<p><code>PDFServlet</code> sends the PDF document to the client by
writing bytes to the servlet's output stream.  It obtains the output
stream by calling <code>getOutputStream()</code> on the <code>HttpServletResponse</code>
object. <code>getOutputStream</code> returns an object of type <code>javax.servlet.ServletOutputStream</code>.</p>
<pre><code>ServletOutputStream sos;
sos = resp.getOutputStream();
baos.writeTo(sos);
sos.flush();</code></pre>
<p>After writing all data to the stream, call the <code>flush()</code>
method to send all bytes to the client.</p>
<h4>Packaging and Deployment</h4>
<p>To run the <code>PDFServlet</code> in Tomcat, you'll need to package
the application in a WAR file.  The iText JAR file (<i>itext-0.99.jar</i>)
must be placed in the WAR file's <i>lib</i> directory. If you forget to
include the iText JAR file, the servlet will fail with a <code>java.lang.NoClassDefFoundError</code>.</p>
<h4>Running the Application</h4>
<p>After the WAR file has been deployed, you are ready to test the
servlet. Jakarta Tomcat listens for requests on port 8080.</p>
<p>Point your web browser to <em>
<a class="moz-txt-link-freetext" href="http://hostname:8080/pdfservlet/createpdf">http://hostname:8080/pdfservlet/createpdf</a></em>.</p>
<p>When you visit the URL, the servlet executes and sends a PDF
document back to your browser.</p>
<h3>Beyond iText</h3>
<p>iText provides a great low-level API for producing PDF documents.
However, it may not be the best tool for every application.</p>
<p>At my day job, we used iText in combination with Microsoft Word and
Adobe Acrobat. First, our team designed a shipment form using Microsoft
Word.  Next, we converted the Word document to PDF using Adobe Acrobat.
Then, using iText's template capability, we loaded the PDF file into
our application. From there, it was quite easy to fill in data values
on the form and output the final PDF document.</p>
<p>For report-oriented web applications, tools like <a
 href="http://jasperreports.sourceforge.net/">JasperReports</a> provide
a higher level of abstraction than iText.</p>
<h3>Conclusion</h3>
<p>When your Java application needs to dynamically create PDF
documents, the iText class library is a great solution.  You can
experiment with iText's capabilities by enhancing and extending the
code in this article. In a short time, you'll be able to impress your
co-workers and customers with sophisticated PDF documents.</p>
<h3>Additional Resources</h3>
<ul>
  <li><a href="http://www.lowagie.com/iText/">http://www.lowagie.com/iText/</a></li>
  <li><a href="http://www.jpedal.org/">www.jpedal.org</a></li>
  <li> <a href="http://www.pdfbox.org/">www.pdfbox.org</a></li>
  <li><a href="http://xml.apache.org/fop/">xml.apache.org/fop</a></li>
  <li><a href="http://www.w3.org/Protocols/">HTTP 1.1 protocol
specification</a></li>
  <li><a href="http://www.faqs.org/rfcs/rfc2183.html">RFC 2183</a></li>
  <li><a
 href="http://dmoz.org/Computers/Data_Formats/Document/Publishing/PDF/">
dmoz.org/Computers/Data_Formats/Document/Publishing/PDF</a></li>
  <li><a href="http://www.planetpdf.com/">www.planetpdf.com</a></li>
  <li><a href="http://www.pdfzone.com/">www.pdfzone.com</a></li>
</ul>
<p>If you are exploring Microsoft's .NET platform, be sure to check out <a
 href="http://sourceforge.net/projects/itextdotnet/">iTextdotNet</a> and <a
 href="http://sourceforge.net/projects/itextsharp/">iTextSharp</a>. 
Both projects are derived from the Java-based iText library. 
iTextSharp is written in Microsoft's C# language.</p>
<p><i> <a href="http://www.onjava.com/pub/au/1230">Sean C. Sullivan</a>
has been developing Internet applications with Java since 1996.  His
recent work includes B2B web applications, various open source projects
and the development of an Internet e-commerce payment system at Intel. </i></p>
<hr size="1" noshade="noshade">
<p>Return to <a href="http://www.onjava.com/">ONJava.com</a>.</p>
<p><font face="verdana,arial,helvetica" size="1"><b>oreillynet.com</b>
Copyright &copy; 2003 O'Reilly &amp; Associates, Inc.</font></p>
</body>
</html>