pdfDebug

Installing iText 7 pdfDebug for Eclipse

We will walk you through the installation process, from downloading iText 7 pdfDebug to setting it up in your IDE.

pdfDebug catches PDF output bugs easily and early

pdfDebug catches PDF output bugs easily and early

Release iText 7.1.4

iText 7.1.4 is the fourth maintenance release for iText 7 Core/Community. We're also updating pdfHTML, pdfCalligraph, RUPS and our License Key and Volume License Key Library.

Release iText 7.0.0

With the release of iText 7, redesigned from the ground up, even more features and functionalities are now at developers' fingertips. iText 7 Community comes with the AGPL license.

Release iText 7.0.1

iText 7.0.1 is our first functional product update. It's a maintenance release that fixes a number of minor bugs, re-syncs the Java and .NET versions and better supports C#. In addition, it falls back on an expanded volume of finished product documentation, examples and Q&A items that were still work in progress when 7.0.0. was released.

Release iText 7.1.3

iText 7.1.3 is the third maintenance release for iText 7.1 Core/Community. We're also updating pdfHTML to 2.1.0, pdfSweep to 2.0.2, pdfCalligraph and pdfInvoice to 2.0.1, and our License Key Library and Volume License Key Library to 3.0.3.

pdfDebug: A look at how it works

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.

Article type
Technical notes

Debugging your PDFs as you make them - for free

While you’re making PDF files and an error occurs, tracing where the problem is can be hard. That’s why we have developed the pdfDebug add-on for iText 7. It allows you to view your PDF file’s internal content structure, content streams and allows you to browse the document in a logical manner – as it is being created. This practical tool is the first of its kind for PDF.

What's even better: We're offering the add-on free of charge through the Eclipse Marketplace so you can see how useful it is for yourself. pdfDebug is currently compatible with Eclipse Neon (4.6), Mars (4.5), Luna (4.4), Kepler (4.3), Juno (4.2, 3.8).

If you need help on how to install pdfDebug, watch this video. You can also watch this tutorial to get you started with pdfDebug's awesomeness.

Not an Eclipse User? Let us know what IDE we should launch next with our quick survey.

Article type
Technical notes

Can I change the page count by changing internal metadata?

Where can I read more about the internal structure of a PDF document?
Contact

Still have questions? 

We're happy to answer your questions. Reach out to us and we'll get back to you shortly.

Contact us
Stay updated

Join 11,000+ subscribers and become an iText PDF expert by staying up to date with our new products, updates, tips, technical solutions and happenings.

Subscribe Now