pdfDebug: A look at how it works

Tags: pdfDebugPDFtutorialdevelopers

pdfDebug is an add on component that is available for iText 7. Its basic function is to allow a programmer to see inside of a PDF while it is being created. This allows for advanced debugging on programs that use iText to create or manipulate PDFs.

Interested? Let’s take a look at how it works with an example.

To start, we created a simple program whose goal is to create a pdf that has four pages, with one phrase on each page. Page 1: Hello World, Page 2: Hello People, Page 3: Hello Everyone. In addition, we want the headers Item 1, Item 2, or Item 3 depending on the page which it appears on and the phrase Good bye on the last page. Below is the code that attempts to achieve this goal.

pdfDebug sample code

Once we run this code however, we find that the headers are not present in the pdf that is created.

pdfDebug Hello world example

To try and rectify this problem we can start debugging by clicking the debug button.

Debugging in action

Great! Some information. But, unfortunately while there are a number of things to look at, there is no simple way to see what has gone wrong with the PDF itself. Looking at the PDF object does not yield much information that is useful to us in this scenario. This is where pdfDebug comes in. To add it to our workspace is a very simple operation, it can be downloaded right from the Eclipse Marketplace here. To install the plugin the install button can be dragged into the Eclipse workspace (Ta Dah!). A dialog will appear as shown below. Simply select pdfDebug and follow the prompts to install it.

pdfDebug prompt

After installing the plugin there is one more change that must be made to be able to use pdfDebug. The pdf writer must be set to debug mode. This can be done with the code change in the screenshot below.

set to debug mode

Once we have this installed we can try debugging again and see what more information we are able to access now that we have pdfDebug installed. If we click on the PDF Document variable when we are debugging we are able to see the structure of the pdf.

pdfDebug view

Now this gives you some more information. With this new view we can see each piece of content as it is added to the PDF. Hello World is added to the PDF and we can see the PDF syntax that describes it inside of the PDF.

pdfDebug content stream

/F1 describes the font that it is added to the PDF in. /F1 is not universal but depends on how /F1 is defined inside of this particular PDF. We can see how it is defined by looking at the resources as shown here:

pdfDebug in action

The second line of description for Hello World tells us where in the PDF it will appear. The coordinates are described with the x coordinate being first and the y coordinate being second. If we continue to step through the program that we have created, we can see that Item 1 is added to the PDF as well with a very similar description. If we look at the coordinates given to for Item 1 however, we can see that there is a problem with them. We see that the coordinates are 36 and 862.98. If we look at the Media Box for the page, which is the coordinates in the PDF that are shown, it has coordinates of 0,0,595,842.

debugging coordinates

means that it starts at 0 for x and y and ends at 550 x and 860 y. The problem we can guess is that the coordinates for Item 1 are outside the media box for the PDF. That means that it is a part of the PDF, but it is outside what is visible so it cannot be seen in the final PDF.
We can now try to modify our code to see if the supposition above is correct. Below is a modification of the code which puts the coordinates of Item 1 inside of the media box.

pdfDebug media box

Once we run the modified code we can again see that Item 1 and all subsequent items are present in the PDF.

Hello World pdfDebug

Lastly, if we debug one more time to look at the other pages of the PDF as it is being created we can see that as things change in the PDF structure, they change color in the same way that they do in the Eclipse debugger.

PDF debugging object tree

Once you are finished debugging your PDF, it will render as expected: (Page 1: Hello World and header, Page 2: Hello people and header 2, Page 3: Hello everyone, header 3 and Good bye.)

PDF debugging final result

As you can see, the ability to see the content structure of the PDF makes it much easier to debug not only initial errors, but other changes in the document from your changes pdfDebug differs from rups and other debugging information because it allows you to both debug existing PDFs and PDFs while they are in creation. Using iText allows for PDFs to be created and manipulated easily, but by this abstraction comes with the downside that the insides of the PDF are not easily understood. By using pdfDebug developers are able to see into their PDFs in a simple way which allows developers to leverage iText for their PDF needs and understand the details when something goes wrong in development

Try if yourself! Download pdfDebug on the Eclipse marketplace here.

You will need iText 7 to test pdfDebug, either an OpenSource iText 7 Community Version or a free trial that you can download here.

We have tutorials for you as well, check our website for help getting started!

Not an Eclipse user? Tell us what IDE we should launch next! Vote here.