Crionics LOGO

FREQUENTLY ASKED QUESTIONS

 

  1. General
    1. What is jPDF?
    2. What are the current modules available?
    3. What is the future of jPDF?
    4. Why did we build jPDF?

  2. Requirement / Limitations
    1. On which architecture/JVM does jPDF work?
    2. Can jPDF run on a Microsoft JVM?
    3. How much memory does jPDF use?
    4. Does jPDF have any restrictions?
    5. Does jPDF require Acrobat Writer to run?

  3. Licensing
    1. How is jPDF licensed?
    2. Do you count Silicon or Computers?
    3. Do we need a developer license?
    4. Do you offer an OEM program?
    5. How does the upgrade policy work?

  4. Common API
    1. Does jPDF support multithreading?
    2. Does jPDF support encryption and signature?
    3. Can several PDF generation requests be processed at the same time?
    4. How fast is jPDF?
    5. Is it possible to process a PDF from memory?
    6. Does jPDF support LZW streams?
    7. Which version of PDF does jPDF support?
    8. I'm trying to stream a PDF file from a servlet and I'm having some trouble. What's the problem?
    9. What are standard, hybrid and 1.5 documents?
    10. What kind of PDF documents can jPDF work with?
    11. What are the benefits of PDF 1.5 documents?

  5. Template API
    1. Images appear upside down after replacing them. Why?

  6. Merger API
    1. Can I use the merge/split functions with ArrayByteReader (document in memory)?

  7. Creator API
    1. Can it modify an existing document?
    2. What is the maximum size for a document?
    3. I get a ZLIB error ?!

  8. Signer API
    1. I get a java.security.cert.CertificateParsingException: signed fields overrun. What does it mean?
    2. The signer complains about JCEKS not being properly installed.

  9. Encryption API
    1. Ciphering a PDF document takes a very long time. What can I do?

  10. Viewer API
    1. How to improve rendering performances?
    2. Is there support for the JBIG2 image format?
    3. Asian fonts sometimes show bulky, what's wrong?
    4. How to install ImageIO?

  11. Troubleshooting
    1. How does one optimize/purge cache operations?
    2. I get the message <invalid license>. What should I do?
    3. My browser always display the same PDF document, no matter how many form updates take place. Why?
    4. I get an error or blank page when viewing redirected PDF in Internet Explorer 3.0 or later.
    5. I get a "Can't connect to X11 window server" error.
    6. On Unix, I get a "error while loading shared libraries: libhpi.so: cannot open shared object file: No such file or directory error. What can I do?
    7. On OpenVMS, I get a class not found exception but jpdf.jar is in the PATH. What's wrong?
    8. I am getting a ClassNotFound error; we use the PJA library.

  12. Miscellaneous
    1. I think I found a bug/problem. How do I report it?

    I. General

      1. What is jPDF ?

        2. jPDF is a suite of 100% Java libraries that allows batch manipulations of PDF documents.
        Current functionalities include form field updates, document merging, signature, printing, content creation and rendering.

      2. What are the current modules available ?

        • Template
        Allows the updating and modification of form field values and attributes present in a PDF Document. Form fields are updatable widgets that are part of the PDF document. They can be dynamically updated at runtime.
        • Merger

        Allows the merging and splitting of PDF Documents.

        • Signer

        Allow the use of digital signatures to seal the document contents and assign it an owner. Can also protect documents by assigning access restrictions and a password.

        • Viewer

        Displays PDF documents on the screen.

        • Printer

        Prints documents to your local printer. Can also convert to gfx formats.

        • Creator

        Creates reports and documents.

      3. What is the future of jPDF ?

        4. Bright and full of useful new features!

      4. Why did we build jPDF ?

        5. For some of the same reason you are currently reading this FAQ.
        We were looking for an easy, fast, 100% Java solution to process PDF documents. Since none were available we had to build our own.

    II. Requirement / Limitations

      1. On which architecture/JVM does jPDF work ?

        2. Because jPDF is a 100% Java application, it runs on any platform that supports a JVM 1.2 or higher. jPDF was reported to work successfully on all Sun and IBM JVMs on OS ranging from Windows, Linux, Solaris and HPUX to OS/390 and OpenVMS.

      2. Can jPDF run on a Microsoft JVM ?

        3. No, because it isn't Java 1.2+ compliant.

      3. How much memory does jPDF use ?

        4. There is no direct answer to this question. But here is how jPDF deals with memory allocation:
        • jPDF stores PDF objects in a cache. This cache cleanup relies on the JVM garbage collector.
        • jPDF doesn't read the complete PDF document in memory. It only parses and reads the information it needs.
        In conclusion, it really depends on how the garbage collector is implemented in the JVM and the structure of the document.

      4. Does jPDF have any restrictions ?

        5. None, other than patent limitations.

      5. Does jPDF require Acrobat writer to run ?

        6. No. jPDF is 100% Java and runs on its own. Starting with Version 6 of the API, jPDF can create all kinds of form fields natively.

    III. Licensing

      1. How is jPDF licensed ?

        2. Crionics offers two kinds of products: Server side and client side.

        The server side products - Merger, Template, Printer, Signer, Creator - have a licensed based on the number of CPUs. For instance if you computer has a bi-processor, you will have to buy two licenses.

        Client proucts however, are leased on a 12 months period.

        Please refer to the following page for further details.

      2. Do you count Silicon or Computers ?

        3. Please refer to the following page for further details.

      3. Do we need a developer license ?

        4. No, a developer license is not mandatory to program jPDF. If you deployed a license in production and are trying to develop at the same time (supposedly on a different computer), you might run into a licensing conflict since you are now running two jPDF instances: the one in production and the one used for development.
        Development licenses are available for purchase at a fraction of the cost of production licenses.

        Please refer to the following page for further details.

      4. Do you offer an OEM program ?

        5. Yes. Please contact us for further details.

      5. How does the upgrade policy work ?

        6. See our support and maintenance section.

    IV. Common API

      1. Does jPDF support multi-threading ?

        2. Yes, at the document level.
        In other words, a given PdfDocument instance is single-threaded (all methods are synchronized).
        But you can create as many instances as you like and each of them will run concurrently.

      2. Does jPDF support encryption and signature ?

        3. Yes. jPDF uses 48 & 128 bits encryption with RC4 and AES. jPDF Signer also support the new crypto filters part of PDF 1.5.

      3. Can several PDF generation requests be processed at the same time ?

        4. Yes as long as you create a new PdfDocument instance for each of them.

      4. How fast is jPDF ?

        5. jPDF is extremely fast due to the fact that the PDF engine uses an intelligent and dynamic cache algorithm.
        Furthermore, after every new revision, the complete API is profiled in order to eliminate performance bottlenecks.

      5. Is it possible to process a PDF from memory ?

        6. Yes, using an ArrayByteReader. Yet this solution is not recommended as the whole document is loaded in memory.
        For most applications, the internal cache engine will address the performance concerns.

      6. Does jPDF support LZW streams ?

        7. The LZW algorithm is patented by Unisys. The patent expired on June 10th 2003, we have LZW support since then.

      7. Which version of PDF does jPDF support ?

        8. Any versions up and including Acrobat 8. We will always try to support the latest specification.

      8. I'm trying to stream a PDF file from a servlet and I'm having some trouble. What's the problem?

        9. The problem usually manifests itself as junk characters shown on screen. The problem persists even though you have set the correct mime type.

        The short answer is, don't depend on IE to display a binary file type properly if you stream it via a servlet. Every minor version of IE has different bugs on this issue.

        The problem in most versions of IE is that IE does not use the mime type on the HTTP response to determine the file type; rather it uses the file extension on the request. Thus you might want to add a .pdf to your request string. For example http://yourserver.com/myServlet.pdf?param1=xx.
        This is easily accomplished through URL mapping in any servlet container. Sometimes a request like http://yourserver.com/myServlet?param1=xx&dummy=file.pdf is also known to work.

        To guarantee opening the file properly in Acrobat from IE, write out your file to a temporary file under your web root from your servlet. Then send an http response to the browser to do a client-side redirection to your temp file.

        Note also that when you request a document that is opened with an external handler, IE sometimes makes two requests to the web server. So if your generating process is heavy, it makes sense to write out to a temporary file, so that multiple requests happen for a static file.

        None of this is particular to Acrobat. The same problem arises when you try to generate any binary file dynamically to an IE client. For example, if you generate XSL/XML files, you will come across many of the same issues.

      9. What are standard, hybrid and native 1.5 documents ?

        10. The "standard" format refers to the way Acrobat documents were encoded tbefore Acrobat 6.0 was released.
        With Acrobat 6.0 - Adobe introduced a new, optimized format that significantly reduces the size of the generated document. The new format is referenced as the 1.5 "native" format which can only be read with viewers or tools (such as jPDF) that support it.

        To overcome this limitation Adobe created a format called "hybrid" in which both structures coexist in the same PDF file. This format allows the new features in PDF 1.5 to be hidden from legacy viewers.

      10. What kind of PDF documents can jPDF work with ?

        11. jPDF can work with any kind of PDF documents : standard, native 1.5 or hybrid. It also knows how to update all of these formats.

      11. What are the benefits of native PDF 1.5 documents ?

        12. Size! Because of their internal structures, native PDF 1.5 documents are more compact and use approximately half the space of regular documents. You can only read these documents with Acrobat 6.0 reader or better.

    V. Template API

      1. Images appear upside down after replacing them. Why ?

        2. PDF stored image data as raw (x,y) coordinates. When the picture is stored in the document, there is no way to figure out if the picture has the right orientation.
        Therefore when you replace an image it may appear upside down or left-side right depending on how the original image was encoded.
        Please check the jPDF template API, as some replacing functions come with an extra parameter for the image rotation.

    VI. Merger API

      1. Can I use the merge/split functions with ArrayByteReader (document in memory) ?

        2. During a merge/split, the new document is being saved several times to free up memory resources.
        Due to this requirement, this particular document must be accessed via Disk I/O and not Memory I/O.
        However, the other documents, the ones being added or being split can exist as a ArrayByteReader.

    VII. Creator API

      1. Can it modify an existing documents ?

        2. Yes, you can append pages and draw new content on existing document pages. that is, assuming the document's author has already authorized content modification.

      2. What is the maximum size for a document ?

        3. Approximately 2 GB. jPDF Creator adds the ability to do incremental updates to release memory resources.

      3. I get a ZLIB error ?

        4. There are many reasons behind such error. Most typically when using the Creator module, you are working on a document, drawing primitives using a Graphics2D instance on a PDF page.
        You probably forgot to call g2d.dispose(). Dispose should always be called on a PDF Graphics2D object.

    VIII. Signer API

      1. I get a java.security.cert.CertificateParsingException: signed fields overrun. What does it mean ?

        2. jPDF picks the first defined X509 provider, as defined in the file <JRE_HOME>/jre/lib/security/java.security, to read certificates.
        The problem depends on the JDK version and the order in which JCE providers are defined. For instance if you run JDK 1.3, the default X509 provider cannot parse the given certificate.
        To fix this issue, you can either switch to the latest version of the JDK (1.4.2 is fine) - or change the order of the JCE providers in the file java.security.

      2. The signer complains about JCEKS not being properly installed

        3. This problem typically happens on JDK 1.3 - where users must install their JCE manually. It is related to a misconfiguration in the JCE extension. To solve the issue:

      • Download the latest JCE from Sun's website.
      • Copy the provided JAR files in <JRE>/lib/ext
      • Edit the file <JRE>/lib/security/security.policy and add a line such as security.provider.2=com.sun.crypto.provider.SunJCE

    IX. Encryption API

      1. Ciphering a PDF document takes a very long time. What can I do ?

        2. First of all, ciphering a document is a heavy process that also depends on the length of the ciphering key. Yet, we have identified some problems with the Sun and IBM JDK versions 1.4.0 and 1.4.1, which have problems with their respective JCE providers.
        To fix the issue, you can either switch to a different JDK version: 1.4.2, 1.3 and 1.2 were reported to work.
        Or you can use install a new JCE provider like the one from Bouncy Castle.

    X. Viewer API

      1. How to improve rendering performances?

        2. First of all, jPDF Viewer is a 100% Java library. While Java performances improved a lot over the past few years, it would be foolish to compare rendering speeds with a native PDF viewer. With that said, PDF rending speeds are usually acceptabl, you can improve performances by:

        Installing ImageIO native image codecs (also known as Java Advanced Imaging). ImageIO is a standard API to read graphic files, it has native support (through .dll or .so) for most file formats. jPDF uses the API if it finds it in the classpath. Since image processing in a quite heavy process, using a native library increases tenfold rendering speeds.

        Improving the JVM default memory: jPDF only reads the data it needs from the document. It also uses caching at different layers to improve performances. Increasing the memory size means that jPDF can store more data in these caches. You may increase the default memory size by using the -Xmx jvm flag.

        Last but not least, use the latest JVM. jPDF uses hardware acceleration and video memory when possible. You can expect significant speed improvements when using JDK 1.6 or better.

      2. Is there support for the JBIG2 image format?

        3. JBIG and JBIG2 are patented algorithm. Implementing such codec in our products will put our company and your company at risks. You may add JBIG support by writting a ImageIO plugin for such formats.

        Unlike many of our competitors, we do respect copyrights and patents. When you purchase a product from Crionics Inc, you purchase a piece of engineering that was developed on American soil. We do not endorse outsourcing or the stealing of technological secrets.

      3. Asian fonts sometimes show bulky, what's wrong?

        4. Asian fonts typically use a technique called "Kerning". Kerning is a little program part of the font itself, that helps render asian glyph correctly. Unfortunatly, it is also a patented technology.

        Unlike many of our competitors, we do respect copyrights and patents. When you purchase a product from Crionics Inc, you purchase a piece of engineering that was developed on American soil. We do not endorse outsourcing or the stealing of technological secrets.

      4. How to install ImageIO?

        5. ImageIO is an image framework based on native libraries, its use will greatly improve the rendering performances of jPDF.

        You may download it from https://jai-imageio.dev.java.net/binary-builds.html.
        Make sure to pick the right platform.

        Note that on MacOS, ImageIO is part of the system.

    XI. How To / Troubleshooting

      1. How does one optimize/purge cache operations?

        2. Each document has an associated object cache, so the best way to optimize I/O is to leave the document open and reuse it. Any call to Document.close() will not only purge the internal document structures, but also purge the associated cache entries.

      2. I get the message <invalid license> What should I do ?

        3. This can happen in one of the following situations:
        • You are running jPDF on an unlicensed IP host. Check your system hosts file and see if 'ping yourhostname' returns the licensed IP.
        • The number of CPUs in your system may have changed. This is particularly true for enterprise virtual systems where the number of CPUs per region can be dynamically changed.
        • Your trial license may have expired.
        • You might be running more instances of jPDF than allowed by your license.
        • The feature you are accessing in not entitled in your license. In other words, you don't have access to this feature.

      3. Why does my browser always display the same PDF document, no matter how many form updates take place ?

        4. This is a common problem with online PDF documents: they get cached either by the browser itself or by a caching firewall/gateway on the network.
        One solution is to follow the code examples bundled in the distribution. They should fix 98% of the problems by using a GET method to request the document as well as a random URL parameter.

        For the 2% remaining: You must be using an old version of IE and/or Acrobat. Try to upgrade to the latest standards. Also, give Netscape/Mozilla Firebird a try: these two browsers follow the HTTP spec accordingly and usually display the documents with no problems.

        If those two options do not work, your last chance is to have jPDF Render the form field appearance directly.

        Preferences prefs = new Preferences();
        prefs.setGenerateAnnotations(true);
        doc = new PdfDocument("myfile.pdf", prefs);

        You might also want to check this tutorial.

      4. I get an error or blank page when viewing redirected PDF in Internet Explorer 3.0 or Later

        5. Starting with jPDF version 6.0 - you shouldn't get these errors anymore. jPDF now renders all appearances natively.

        This issue is documented at Adobe: http://www.adobe.com/support/techdocs/1c1ae.htm

         

      5. I get a "Can't connect to X11 window server" error.

        6. This is a known issue with JDK versions <= 1.3 running on Unix. With these JDK, the JVM requires a graphical display as soon as a Java2D method is accessed. Even if it doesn't do any Graphics2D operation.

        This bug has been fixed with version 1.4 of the JVM, where the following command line parameter will solve the issue.

        -Djava.awt.headless=true

        On VMS use: "-Djava.awt.headless=true"

        If you run JDK 1.3/1.2 things are a little more tricky, but not really complex. You can either choose to tweak the OS or Java,. Both solutions will work.

        • Tweaking the OS by creating a virtual display:
          Most Unix distributions come with the xvfb (X Virtual Frame Buffer) program which creates a virtual display in memory. The sample script below starts the xvfb process in the background, sets the DISPLAY variable and allows connections. Once the script is run, your application should work.

          >xvfb :99 -screen 0 1x1x8 &
          >set DISPLAY=:99
          >xhost +

        • Tweaking Java by using a different AWT implementation:
          PJA (Pure Java AWT toolkit) is a graphics library for drawing graphics developed by eTeks. It is 100% Pure Java and doesn't use any native graphics resource of the system on which the Java Virtual Machine is running (X Server, for instance).  This allows you to get the same functionality you would from the native awt libraries, without concern for the operating environment.
          Just adding the pja.jar in the application classpath and adding the following parameter on the command line will do the trick.

          -Xbootclasspath=/path/to/pja.jar  -Djava.awt=com.eteks.awt.PJAToolkit -Djava.awt.graphicsenv=com.eteks.java2d.PJAGraphicsEnvironment  -Djava.awt.fonts=/path/to//java/jre/lib/fonts

        On OpenVMS, in order to start Tomcat with the headless parameters, you will need to create a special configuration file, the procedure is described here.

      6. On Unix, I get a "error while loading shared libraries: libhpi.so: cannot open shared object file: No such file or directory" error or something similar. What can I do ?

        7. Your JVM is not installed properly: somewhere, somehow you are pointing at the wrong version of the shared libraries - most likely from a different JDK in your system.

      7. On OpenVMS, I get a class not found exception but jpdf.jar is in the PATH - what's wrong ?

        8. All files read by the JVM must be converted to the stream_lf format. This includes JAR files of course, but also the PDF files! Use the following command to process the conversion.

        $ set file/attr=(rfm:stmlf, rat:cr) name_of_file

        More information can be found in the OpenVMS JDK release notes.

      8. I am getting a ClassNotFound error; we use the PJA library.

        9. Check the logs; you should also get this exception: com.eteks.java2d.PJAGraphicsEnvironment, If you are running JDK 1.4 or better - the version of PJA might be outdated - please install version 2.5 or better.
        It will fix the problem.

         

    XII. Miscellaneous

      1. I think I found a bug/problem, how do I report it ?

        2. First, make sure your problem is not addresse in our FAQs.
        Second, isolate the problem with a simple test case, then send us the document and the associated test case.
        We will fix it as soon as possible.
        The support e-mail address: support@email.com
     

    © 2000-2007 Crionics Inc. Report issues with this page