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.

- It doesn't seem to be possible to catch malloc errors since the JNI
  exits before the PDFlib error handler jumps in.


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. Absolute
  path names work. For this reason the output of the supplied PDFlib samples
  may end up in some strange place.


Using PDFlib with Allaire 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 JServ
==============================

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

- Add the following lines to the file jserv.properties (adjust the path
  names appropriately for non-Windows platforms):

    wrapper.classpath=c:\winnt\system32\pdf_java.dll
    wrapper.classpath=c:\winnt\system32\pdflib.jar


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

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.


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.


Building the PDFlib Java wrapper on S/390 with Unix System Services
===================================================================

PDFlib's configure script currently isn't able to build a PDFlib DLL
for use with Java. In order to do this manually, you must first run the
configure script and build the PDFlib core library by doing a make
in the pdflib subdirectory. You will need the IBM c89 ANSI C compiler.

Next, compile and link the PDFlib Java DLL using the following commands
in the bind/java directory:

c89  -0 -c -o pdflib_java.o -W c,expo,dll -Wc,"GONUM" \      
 -DOS390 \                                                  
 -I /usr/lpp/java/J1.1/include \                            
 -I /usr/lpp/java/J1.1/include/mvs \                        
 -I ../../pdflib pdflib_java.c

c89 -W l,dll -o libpdf_java.so pdflib_java.o \              
 ../../pdflib/pdflib.a  \                                    
 /u/zlib/libz.a \                                 
 /usr/lpp/java/J1.1/lib/mvs/native_threads/libjava.x \      
 /usr/lpp/java/J1.1/lib/mvs/native_threads/libJNIConvert.x

Finally, you can compile the PDFlib Java wrapper, and build the PDFlib
package using the jar utility:

mkdir -p com/pdflib                                                
javac pdflib.java                                                  
mv pdflib.class com/pdflib                                         
jar cvf pdflib.jar com/pdflib/pdflib.class                         
rm -rf com                                                         
CLASSPATH=$CLASSPATH:pdflib.jar:.

In order to use a PDFlib dynamic link library (DLL), the application
(e.g., the Java VM in the case of the PDFlib Java binding) must
have access to the DLL, e.g. via the LIBPATH environment variable.

Note: we plan to make S/390 binaries available soon -- please check
our Web site.
