Using the JSP and servlet examples
==================================

Before using the examples you must either copy the relevant
image and PDF files to an appropriate location, or modify
the paths in the source code to point to the sample files.


General notes on the PDFlib Java binding
========================================

- Older JDK versions up to 1.1.8 are known to have multiple bugs with
  respect to timezone interpretation. For this reason chances are that
  the pdfclock example will display the wrong time on your system.

- The PDFlib Java wrapper cannot be compiled under Cygwin due to an
  imcompatibility between the JNI headers and Cygwin.

- Memory management and garbage collection: if you are running low on
  memory or want to reduce memory usage of your application it is
  recommended to explicitly call the delete() method before the PDFlib
  object goes out of scope. This is useful because the finalizer/garbage
  collector may kick in late, maybe too late.


Using PDFlib with IBM Visual Age for Java
==========================================

- Add pdflib.jar to your project.

- Place pdf_java.dll in the \winnt\system32 directory, or some 
  other directory contained in the PATH environment variable.

- Relative pathnames in PDFlib function calls are interpreted relative
  to the java bin directory, not the project directory. For this reason
  the output of the supplied PDFlib samples may end up in some strange
  place. Absolute path names work.


Using PDFlib with Borland/Inprise JBuilder
==========================================

- Having pdflib.java in the same directory as the project file
  seems to confuse JBuilder.

- On Windows pdf_java.dll must be placed in the \winnt\system32 directory,
  or some other directory contained in the PATH environment variable.
  On Linux libpdf_java.so should be placed in /usr/lib or a similar
  well-known (to the system) directory.

- Relative pathnames in PDFlib function calls are interpreted relative
  to the JBuilder bin directory, not the project directory.  For this
  reason the output of the supplied PDFlib samples may end up in some
  strange place. Absolute path names work.


Using PDFlib with Macromedia JRun
=================================

In order to use PDFlib with JRun the following is suggested:

- Copy PDFlib.jar and lib_java.dll to the .../JRun/servers/lib directory.

- Make sure that the lib directory is contained in the servlet.jnipath
  property. This property can be set from the management console, or
  specified in a local.properties file.


Using PDFlib with J2EE-compliant servers
========================================

In order to use PDFlib with J2EE do the following:

- Add the following lines in the file $J2EE_HOME/lib/security/server.policy
  in order to allow the PDFlib native library to be loaded:

  // default permissions granted to all domains
  grant {
          permission java.lang.RuntimePermission "loadLibrary.*";
          permission java.lang.RuntimePermission "accessClassInPackage.*";
          ...

- Use the deployment tool to add pdflib.jar to the project as an external
  jar library.
  It seems that pdflib.jar must be placed in the %J2EE_HOME%/lib directory;
  otherwise the server will attempt to load the PDFlib shared library
  multiply, resulting in the error message "shared library already loaded".

- pdf_java.dll or libpdf_java.so must be accessible in some system path,
  e.g. \winnt\system32 or /usr/local/lib, or via PATH/LD_LIBRARY_PATH.

- The PATH and CLASSPATH variables should point to the bin subdirectories
  of J2EE and JDK.


Using PDFlib with Apache mod_jserv
==================================

In order to use PDFlib with Apache JServ do the following:

- It is suggested to load PDFlib as early as possible. Loading PDFlib later
  in the servlet (e.g., via repositories) may fail due to a different
  class loader.

- Add the following (probably modified) lines to the file tomcat.properties:

    wrapper.env="/usr/local/lib:/usr/lib:/lib"
    wrapper.classpath=/usr/local/lib/java/pdflib.jar

- After building or installing PDFlib it may help to update the shared
  library cache via

  ldconfig -v		(or similar command depending on your Unix version)

- Restart Apache, and therefore the JVM.


Using PDFlib with Apache JServ
==============================

In order to use PDFlib with Apache JServ do the following:

- It is suggested to load PDFlib as early as possible. Loading PDFlib later
  in the servlet (e.g., via repositories) may fail due to a different
  class loader.

- Add the following (probably modified) lines to the file jserv.properties:

    wrapper.env="/usr/local/lib:/usr/lib:/lib"
    wrapper.classpath=/usr/local/lib/java/pdflib.jar

- After building or installing PDFlib it may help to update the shared
  library cache via

  ldconfig -v

- Restart Apache, and therefore the JVM.


Using PDFlib with IBM WebSphere Application Server
==================================================

Servlets are loaded with a custom class loader. For this reason,
the pdflib.jar file has to be located in the Application Server's
classpath rather than the web application's classpath.  

To locate the pdflib.jar file in the app server's classpath, place the jar 
file in the \<WAS app-server's path>\lib directory and edit the 
admin.conf file.  In the admin.conf file add the path to the jar file 
to the setting labeled:

com.ibm.ejs.sm.adminserver.classpath

If you use the Websphere Application Assembly Tool you can add pdflib.jar
to your project. 

The DLL or .so must be located somewhere on the machine's path.
The winnt\system32 directory works for Windows, the bin directory
of WAS on Solaris.

On the AS/400 make sure that the PDFLIB and PDF_JAVA SRVPGM can be
found in the library list of the jobs running your Java apps. The
easiest way to achieve this is to copy these SRVPGMs to the QGPL
library. In most cases this library is found in every LIBL.


Using PDFlib on Mac OS X
========================

On Mac OS X the shared PDFlib library for Java, which has a default file
name of libpdf_java.dylib, must be renamed to libpdf_java.jnilib. The
PDFlib build process does this automatically.

The default search path for JNI libraries on OS X is as follows:

    .:/usr/lib:/usr/lib/java:/lib:
    /System/Library/Frameworks/JavaVM.framework/Versions/1.2/Libraries

You can extend the JNI search path by defining the DYLD_LIBRARY_PATH
with more directories.


Using PDFlib with Apple WebObjects
==================================

To the best of our knowledge, the following should be sufficient in order
to use PDFlib with WebObjects:

- Use the java-framework-maker tool to create a new WebObjects Framework,
  and select PDFlib.jar as input package.

- Add the new framework to your project.