iText, a free Java PDF library SourceForge.net Logo A Free Java-PDF library
by Bruno Lowagie and Paulo Soares

[Home] [Download] [FAQ] [Links] [Docs]
[SourceForge] [Mail Archives] [MailingList] [Amazon] [CVS]














These are some frequently asked questions

If you don't find the answer to your question here and it's mainly a technical question, please consult the tutorial. On the HOME-page you'll find an overview of all the topics that are discussed in the tutorial. The original mailing list archives can be found at GeoCrawler. Unfortunately these archives are not searchable. The mailing list was mirrored on a searchable mail-archive starting january 20, 2002 at mail-archive.com.


PDF is the 'Portable Document Format', i.e. the native file format of the Adobe(R) Acrobat(R) family of products. The goal of these products is to enable users to exchange and view electronic documents easily and reliably, independent of the environment in which they were created.
Check out the
Adobe
website where you can download some
White Papers
and the
Portable Document Format Reference Manual
for more information.


ADOBE owns the copyright for the PDF specifications, that is true. However, using iText to produce documents in PDF is completely legal.

Please read the PDF Reference 1.4 section 1.4. I quote:
Adobe desires to promote the use of the Portable Document Format for information interchange among diverse products and applications. Accordingly, Adobe gives anyone copyright permission, subject to the conditions stated below, to:
  • Prepare files whose content conforms to the Portable Document Format
  • Write drivers and applications that produce output represented in the Portable Document Format
  • Write software that accepts input in the form of the Portable Document Format and displays, prints, or otherwise interprets the contents
  • Copy Adobe’s copyrighted list of data structures and operators, as well as the example code and PostScript language function definitions in the written specification, to the extent necessary to use the Portable Document Format for the purposes above
The conditions of such copyright permission are:
  • Software that accepts input in the form of the Portable Document Format must respect the access permissions specified in that document. Accessing the document in ways not permitted by the document’s access permissions is a violation of the document author’s copyright.
  • Anyone who uses the copyrighted list of data structures and operators, as stated above, must include an appropriate copyright notice.
Because decrypting an encrypted PDF-file is not possible with iText (and it will never be) and because there are lots of pointers to Adobe and to the PDF Reference Manual everytime some explanation is given about the data structure, iText is allowed to prepare files whose content conforms to the Portable Document Format.


iText is free in the sense that you don't have to pay money to download the product (no purchase price), nor to use it (no license fee). However, this doesn't mean you can do anything you want with iText. If you use iText, you agree with either the Mozilla Public License (with LGPL as alternative license) or the Library General Public License (without MPL). You can read more about these licenses in the next question. These licenses are used mainly to protect the developers against claims from users and to protect the product against abuse. It wouldn't be fair if someone would try to get profit from iText on the back of us, 'benevolent developers' ;-)
If you work for a large company and using iText has saved your company lots of time and money, you can support the developers in several ways:
  • First of all: let us know. Those little mails we get, is it from a student who has used iText in a school project, or from a large company who has used iText in a complex application, those mails are always welcome. We really appreciate them.
  • You can contribute code to ameliorate the library. This doesn't mean you have to send us your whole application (see the license question), but any code that adds value to the library is welcomed.
  • You can share your expertise with other iText users by answering questions on the mailing list. You can save other people lots of time.
  • You can promote the use of iText by posting it to search engines, putting a link on your site, recommending it to other people on mailing lists and user forums, write articles about it in magazines,...
  • If iText really, really saved your company time and money, you can ask your company to donate money to the original developer (Bruno Lowagie) and the co-developer (Paulo Soares).
For the moment there is no possibility to purchase a support contract. Support is given only on a voluntary basis through the mailinglist.


First of all: LGPL IS NOT GPL!
If you work for a commercial company and you download a program that is published with a GPL, I would recommend you to stay away from it, unless you want to use the product AS-IS. GPL is like a virus. It affects all the software you add yourself to the product. That is my point of view. Not everyone has to agree.

iText was originally published by me (Bruno Lowagie) as LGPL! I made iText LGPL because I want to encourage people to use iText in their commercial/closed source/propriety software. I myself use iText in closed source projects.
It is allowed to use iText in your own product as long as you don't change the copyright notices. You also have to distribute the source code of iText to your clients (or even better, add a link to the iText site).
You can't charge your client for iText, nor for the work you have done 'ameliorating iText'. All enhancements or bugfixes have to be published for free.
Of course you may charge people for your own application and for the work you did integrating iText in your product. Your own code may of course remain closed source. For instance: if you write an editor that produces PDF, you can charge your customers for the work you have done on the editor, but not for the PDF generating part. If you have fixed some bugs in iText while writing the code of your product, you have to send a bugreport telling the community how to fix these bugs to the mailing list. Lots of people have contributed to the code; you will find lots of names in the source code.
Once you decide to use iText, you accept the code AS-IS. You can't force any of the developers to give support (allthough you will get lots of free support through the mailing list). You can't sue any of the developers if anything goes wrong. After all, iText is a FREE product.

You can read the LGPL for more detail (see lgpl.txt), but I think the above is a good summary.

Because of some quirky details in the LGPL, people developing commercial products using iText asked me to move to a less strict license. That's why I made iText multiple licensed. iText can be used under MPL too. Read the MPL for more info: MPL-1.1.txt.


First of all, it is better not to send mails to any other address than itext-questions@lists.sourceforge.net. This is the mailing list address, please join this list first. If you send mails to the developers (Bruno Lowagie and/or Paulo Soares), one of us can be on vacation, thus unable to give you a quick reply. Also your mail can get lost (I delete lots of mails without even reading them; surprised? Well, you probably don't receive as many mail as I do). If you post a question to the mailing list, your mail is archived and if you don't get answered, you can always refer to it later on.
Almost all questions on the mailing list are answered, but there are limits. If we get the feeling that you are expecting us to do your school project in your place, or even worse, if you want to do us your work in your place for free, you will get 'NO' for an answer. This is only normal. We've got our own jobs too.


If you are not subscibed and you post a question to: itext-questions@lists.sourceforge.net, you get an automated reply that you aren't subscribed. This means that your question will be put on hold until one of the mailing list administrators has reviewed your mail. Your mail can be approved (thus sent to the other mailing list users) or rejected (if you are sending duplicate mails, spam, off-topic questions,...). This can take a while, so maybe you want to subscribe.
All the information you need to subscribe to this mailing list, can be found at the following address: http://lists.sourceforge.net/mailman/listinfo/itext-questions. If you scroll to the bottom of this page, you can also find the information to unsubscribe.
Before you post a question, it's probably not a bad idea to take a look at the mailinglist achives:


It's very unusual to pay for something that is free, but it happens. I have to pay my webserver hosting bills, I buy books about Java and PDF, Paulo and I spend time at home to write code, write tutorials, solve problems,... We do this on a voluntary basis, but sometimes it's nice to receive a little bonus to cover the costs. (Or in my case: also to make up for the time I spend on iText to my wife and children ;-)
That's why you (or more likely: your company) may want to donate some money to us. If so, send a mail to me (bruno at lowagie.com) and you will receive, my personal address, the name, address and SWIFT code of my bank and my account number. Please specify the amount of money you are willing to donate.
Again: this is not an obligation. This suggestion is not aimed at you as an individual, only at the company you work for, a company that may be making big profits because you chose to work with iText instead of another product. (Personally I would ask for a raise first ;-)



There are lots of features in different versions of MSIE that make it rather difficult to show a dynamically generated PDF file in every browser. I used to have a list with links to MicroSoft's Knowledge Base here, but that list was very hard to maintain.

When you send dynamically created CORRECT (!) PDFs (with ASP, JSP, a Servlet, Cold Fusion) to the client, the client only receives a blank browser window. This is because MSIE needs to know the exact content length of the PDF file in advance!
You can use the following workaround to avoid this:

 res.setContentType("application/pdf");
 ByteArrayOutputStream ba = new ByteArrayOutputStream();
 generate_pdf(ba);
 res.setContentLength(ba.size());
 ServletOutputStream out = res.getOutputStream();
 ba.writeTo(out);
 out.flush();

If you don't include the content length it only works sometimes, if ever.

Another known feature of MSIE: every time a client requests a dynamically generated PDF you see the server receives the same request 2 or 3 times. You can work around this using the following construction posted by Anis H.:

<HTML>
<BODY leftMargin=0 topMargin=0 scroll=no>
  <EMBED src="http://myserver/pdfCreationServlet" width="100%" height="100%" type=application/pdf fullscreen="yes">
</body>
</html>


when you invoke your servlet which creates PDF as shown above only one request will be sent to the server.

In another context (dynamic CSV files over SSL), Nicolas Guichard posted this solution to the mailing-list:
I have the same problem with CSV files, and i just found the solution on a php forum: Following their advice, I add the following parameters to the response's headers:
response.setHeader("Expires", "0");
response.setHeader("Cache-Control", "must-revalidate, post-check=0, pre-check=0");
response.setHeader("Pragma", "public");


And it works.... But don't ask me to explain this!!!


You are invoking the method on the wrong object. You create a PDF document in 5 steps (See Chapter 1 of the tutorial). In the first step, you create a Document-object. A Document-object handles CONTENT, not LAYOUT. In step two you choose 1 or more Writers. For instance: you can get an instance of a PdfWriter that listens to your Document-object, writing content to pages in landscape. You can also add another PdfWriter that listens to the SAME Document object, writing content to pages in portrait.
If you want to know the current pagenumber, what object are you going to invoke the method getPageNumber() on? If you do document.getPageNumber(), will it give you the current number of the file in landscape? Or will it give you the number of the file in portrait? It doesn't know what to do, so it tells you the pagenumber is 0. Just use writer.getPageNumber() for the correct value.


In most of the examples, the pages are created with a PageSize.A4. These pages are shown in portrait. If you create a page with PageSize.A4.rotate(), the pages are shown in landscape. You can also use the setPageSize-method, but be aware of the fact that the PageSize will only be changed on the next page.
This is covered in the tutorial.


Chances are you added the header, footer or watermark at the wrong place. This is covered in the tutorial.


The default measurement system roughly corresponds to the various definitions of the typographic unit of measurement known as the point. This is covered in the tutorial.


When you construct or shape the objects Cell (and/or Table), you create content and metadata that will allow a writer to make a representation of a Cell (and/or Table). At the moment you are doing this, the Cells nor the Table are aware of the presentation format. You could add the object to a Document that is listened to by an HtmlWriter, a PdfWriter, an XmlWriter, an RtfWriter, or a combination of any of these writers. You can have several PdfWriters listening to one Document. For instance one writer that writes to a file that represents a document with A4 portrait as Page Size and another with A4 landscape. Both documents will show the same content and metadata, but the cells (and/or table) will have different dimensions. That is why it doesn't make sense to ask a Cell (and/or Table) object for its dimensions.


No, use Acrobat Reader or GhostView or any other PDF viewer instead.
Carsten Hammer made the following suggestions if you REALLY need a Java solution to view PDFs:
  • Use jpedal. There is an example on their site.
  • Adobe once release a PDF Viewer library: Adobe Acrobat Viewer (for Java). Unfortunately they discontinued the development, so it only supports older versions of PDF and JAVA.
    Carsten provided a jar with an example on how to use the library. You can find this jar here. Just do java -jar pdfviewer.jar. Before you download the zip, please read the License Agreement from Adobe first.


Yes, in some cases, you can: see the example in Chapter 1 of the tutorial. You can extract complete pages of an existing PDF document and copy them to a newly created PDF document.


No, the pdf format is just a canvas where text and graphics are placed without any structure information. As such there aren't any 'iText-objects' in a PDF file. For instance: you can't retrieve a table object from a PDF file. Tables are formed by placing text and lines at selected places.


This is not really supported by iText. In Chapter 7, you find a (very experimental) example. There are people who have succeeded in using this functionality in combination with the HtmlTidy and there are also some examples here (but the links are broken most of the time): http://128.146.184.28/pdfsamples/asp_readme.htm and http://128.146.184.28/pdfsamples/Html2pdf.asp.
If you really need HTML to PDF conversion, use HtmlDoc or post your question to the mailing list to hear from other subscribers how they achieved to parse their HTML.


If the source code doesn't compile, this can be caused by four different reasons:
  1. If the missing classes are for instance java.util.Iterator or java.util.ArrayList, this is a sign that your are not using the JDK1.2. You should upgrade your JDK or use the 1.1.x-version of the library.
  2. If the missing classes are related to XML, you probably forgot to add the iTextXML.jar to your classpath.
  3. If you are missing non-iText classes (for instance org.xml.sax.Parser), you need to put the j2ee.jar in your classpath (in this case the SDK isn't sufficient, you need the Java 2 Enterprise Edition). These classes are not used in the iText.jar library, only in the additional iTextXML.jar.
  4. If you have trouble compiling or running the examples on a WINDOWS-OS, you can use this batch file: compile.bat. Just run it with the name of the example (not the filename) as parameter: for instance: 'compile Chap0101'.
  5. If you are using iText in a Servlet, make sure you have the iText.jar in the right place. If you are using Tomcat 4, and want all of your contexts to have access to the classes for iText, then you can use the $CATALINA_HOME/common/lib folder. If you want only one context, or application on your server to have access to them, they should be placed in a folder that only that context can see. For example, for context, 'myApp', it would be $CATALINA_HOME/webapps/myApp/WEB-INF/lib folder. (answer by Chris Ward).
  6. Any other problem with classes that are not found, are caused by errors in your classpath. You and you alone can solve these kind of errors, so please don't mail us before you're absolutely sure you've checked every detail on your system.


You can download a 1.1 distribution from Paulo's site. You will also need to download the Collection classes to make the library work (more info)


First read Chapter 6 of the tutorial. iText supports images (WMF, plain GIFs, JPEGs and PNGs), but there are some limitations!
    These are the exceptions:
  • GIF
    • Gifs without a global colortable
    • interlaced gifs or gifs using local color table
    • ... (check out the error message!)
  • JPG
    • JPG with of which the number of 'Bits Per Component' != 8
    • JPG with 'invalid JPEG markers' (see the code of class Jpeg)
  • PNG
    • PNGs with BitDepth == 16
    • PNGs with another colortype than 0, 2 or 3
    • interlaced PNGs
GIF is the most delicate format. I followed the GIF specs as good as possible, but you must know that there are also some legal limitations (the format is owned by Unisys and there is a patent on LZW-compression/decompression). When an image is rejected by iText, the exception that gets thrown always gives an explanation; for instance:
the image separator '0x2c' is not found after reading the color table
This is quite a cryptic error message, but the code can't possibly tell you more: in the GIF specs, it is specified that the code 0x2c should be used as imageSeparator (this is the byte that should separate the section with the GIF-header, the info and the color table from the image descriptor). If iText can't find this byte, the library can't do anything with the GIF and rejects it...
You can try using another tool to create your GIF-file, one that generates images that are conform to the specs. You can consider using PNG- or JPG-images instead. Or you can use Advanced iText:
Advanced iText uses the java.awt.Image-object from the JDK, so if you use this functionality (as described in the advanced example in Chapter 6), you can add all the types of images that are supported by the JDK (all kinds of GIFs, TIFF,...).


First you will need to read the file you want to convert:
Reader in = new InputStreamReader(new FileInputStream("your_file_name.txt"), yourEncoding);

If it's just a plain ASCII-file, you don't need to specify the encoding, but this parameter is added to show this functionality can also be used for (a.o.) Asian texts. If you have a Japanese text with encoding Shift JIS, the value of parameter yourEncoding should be "SJIS". With this reader, you can put the text into a String with UNICODE characters.

If your text is preformatted and you don't want to loose the 'layout', you need to put this String in a Paragraph-object that uses a 'fixed width' font and add this paragraph to a document. If you use only romanic characters, you can use the font 'Courier'. Or you can change the width of the characters yourself (as demonstrated in Chapter 9 of the tutorial), but keep in mind that width change only works with type1 and true-type fonts with encodings other then IDENTITY-H or IDENTITY-V.

If you are using an Asian Font, you will have to manipulate the String first.
In the case of Japanese, you can create this BaseFont:
BaseFont bf = BaseFont.createFont("HeiseiKakuGo-W5", "UniJIS-UCS2-H", BaseFont.NOT_EMBEDDED);
Remark: the embedding flag is ignored when built-in fonts and CJK fonts from the Adobe font pack are used. Another option is to use msgothic.ttc or msmincho.ttc; these can be embedded.
You will have to move all characters in the range \u0020-\u007f to the range \uff00-\uff5f. That's the "Halfwidth and Fullwidth Forms" Unicode range. (Another option is to use courier with the romanic characters, but you'll have to change the default widths of 600 to 1000 to match the ideographs.) You can put the resulting String in a Paragraph and add it to a document.


No offense, but if you are reading this question because you need the answer, chances are you are not a very good programmer. Or you are a programmer with bad taste. You just DON'T GENERATE binaries using JSP.
However if you want to see how it is done, you can look up the code in the CVS repository or download the tar.gz or containing the complete set of examples. DO NOT COMPLAIN TO THE MAILING LIST THAT THE EXAMPLE DOESN'T WORK BEFORE YOU CHECK pdf.jsp ON MY SITE. If this example doesn't work for you, it is probably because you added newlines, spaces, carriage returns,... to the original JSP-code. These newlines, spaces, carriage returns,... are added to the PDF and make the file corrupt: the crossreference table doesn't point to the correct bytepositions anymore. SUMMARIZED: iText for JSP is possible, but don't expect to get any support for it.


Printing is a very platform dependent functionality. On Windows, you can print a PDF file by executing Acrobat Reader:
String osName = System.getProperty("os.name" );
//FOR WINDOWS 95 AND 98 USE COMMAND.COM
if( osName.equals( "Windows 95" ) || osName.equals( "Windows 98" )){
    Runtime.getRuntime().exec("command.com /C start acrord32 /p /h" + claim.pdf);
}
//FOR WINDOWS NT/XP/2000 USE CMD.EXE
else {
    Runtime.getRuntime().exec("cmd.exe /C acrord32 /p /h" + claim.pdf);
}

(Code provided by Jasperlan Guela)
Remark: the /h-option suppresses the Acrobat Reader Dialog Box.


Please send your questions about RTF to the mailing-list. The RTF package was developed by Mark Hall. He is a member of the mailing-list and he will answer most of your questions concerning iText and RTF. For more general questions on RTF, you can also consult the RTF FAQ written by Dave Thielen, another active subscriber of the iText mailing-list.


[Previous Page]   [Top]   [Next Page]
Page Updated: $Date: 2003/12/02 10:51:35 $
Copyright © 1999, 2000, 2001 by Bruno Lowagie,Adolf Baeyensstraat 121, 9040 Gent, BELGIUM
Read the Privacy Policy at lowagie.com
mailto:itext-questions@lists.sourceforge.net