Home / Articles / Tools of the Trade, Part 1: Creating PDF documents with iText

Tools of the Trade, Part 1: Creating PDF documents with iText

Article Description

Have you ever wanted to create your own PDF documents without having to first shell out money for PDF-creation software? Good news: You can create those documents with nothing more than Java and iText. This freely available Java library provides the classes for easily constructing PDF documents and adding various kinds of content (such as paragraphs, lists, tables, and images) to those documents. This article by Jeff Friesen, the first in a three-part series that explores useful open-source tools, introduces you to iText and shows you how to create many interesting PDF documents without having to first spend money on PDF-creation software.

iText Intro

iText, created by Bruno Lowagie and Paulo Soares, is an open-source Java library for creating PDF, HTML, RTF, and XML documents. Although you can use iText without paying a fee, this library is licensed to protect the software, its developers, and its users. Learn more about licenses on iText's Download & Compile page.

For working with this article's code, I recommend that you download itext-1.3.jar instead of first downloading and then compiling the iText source code. After clicking the itext-1.3.jar link, you are taken to the SourceForge site, from which you can select an appropriate mirror to download the Jar file. You should also click the itext-docs-1.3.tar.gz link to download iText's library documentation.

After downloading iText's Jar and documentation files, establish a directory structure to organize these files and help you manage your iText projects. I chose the following directory structure on my C: drive:

c:\itext\docs
c:\itext\projects
c:\itext\itext-1.3.jar

The iText directory serves as my home directory for docs (the library's documentation directory—extract itext-docs-1.3.tar.gz's directories and files into this directory), projects (various iText projects directory), and the iText Jar file.

Having established a directory structure, only one other task needs to be accomplished: Set the CLASSPATH. That environment variable must include iText's Jar file and the current directory. For Windows 98 SE, the command to set CLASSPATH is set classpath=%classpath%;c:\itext\itext-1.3.jar;. If you are using a different version of Windows or a non-Windows operating system, study your OS documentation to find out how to set this environment variable.

Now that we have established our directory structure and set the CLASSPATH environment variable, we can explore a Java application that uses iText to create a simple PDF document. Take a look at Listing 1.

Listing 1 Descent.java

// Descent.java

import java.io.*;

import com.lowagie.text.*;
import com.lowagie.text.pdf.*;

class Descent
{
  static String para =

  "Lightning flashed across the sky. Thunder rumbled in the distance. " +
  "The wind began to moan, as if in pain. The good people of the village " +
  "huddled together in the common room. Fear glistened in their eyes and " +
  "their hearts pounded with terror. Evil was descending into their " +
  "valley, and there was nothing they could do to save their lives ...";

  public static void main (String [] args) throws Exception
  {
   Document doc = new Document ();
   PdfWriter.getInstance (doc, new FileOutputStream ("descent.pdf"));
   doc.open ();

   Paragraph p = new Paragraph (para);
   p.setAlignment (Element.ALIGN_JUSTIFIED);
   doc.add (p);

   doc.close ();
  }
}

Listing 1 creates a PDF document consisting of a single paragraph (that we will pretend was taken from a larger horror story called Descent). The source code reveals five steps that iText applications perform to create PDF documents:

  1. Create an instance of the Document class: Document doc = new Document (); accomplishes that task. The Document class describes a document's page size (Letter, Legal, A4, and so on), margins, and other important attributes. It is also a container for a document's chapters, sections, images, paragraphs, and other content.
  2. Create a document writer that writes the equivalent syntax for a document's content to a specific OutputStream (this article always uses PdfWriter to output PDF syntax; other document writers output HTML, RTF, and XML syntax): PdfWriter.getInstance (doc, new FileOutputStream ("descent.pdf")); creates a PDF document writer that writes PDF syntax to file descent.pdf via a FileOutputStream.
  3. Open the document; doc.open (); is all that is required.
  4. Add content to the document. There are many ways to do this. Paragraph p = new Paragraph (para); p.setAlignment (Element.ALIGN_JUSTIFIED); doc.add (p); creates a Paragraph that houses a paragraph of text, tells the PDF document writer to ensure that the Paragraph's text is justified on both sides, and adds the Paragraph to the previously created Document. As content is added, the PDF document writer works behind the scenes to send the equivalent PDF syntax to the file.
  5. Close the document; doc.close (); accomplishes this task. Closing the document is important because it flushes and closes the OutputStream instance to which the document writer is writing syntax.

Now that we have examined the structure of our first iText application, we are almost ready to compile the application's source code. First, however, we must create a Descent directory underneath the projects directory, copy Listing 1 into a Descent.java file, and store that file in Descent.

After accomplishing the previous tasks, compile Descent.java (javac Descent.java). Assuming that you have properly set the CLASSPATH environment variable, you should find a Descent.class file in the Descent directory.

We can now create our first PDF document. Invoke java Descent to run the application. You should observe a descent.pdf file in the Descent directory. View that document by launching your copy of Adobe Reader (or some other suitable PDF document viewer) and opening descent.pdf. You should see something similar to Figure 1.

Figure 1

Figure 1 Your first iText-created PDF document.

Congratulations. You have just created your first PDF document, and it did not cost you anything. The following section builds upon the knowledge you have just acquired by taking you on a tour of important iText classes.

3. Class Tour | Next Section Previous Section